Apache Syncope 2.0 Primer

HOW TO Scenarios

Add Custom Attribute to Syncope Users

Purpose

Often, when Apache Syncope is used to store user data, it becomes important to customize the fields that can be added to user.  For example, if we needed to include an Email address, First and Last names, or any other attributes, the following guide will illustrate how.

Via Apache Syncope Console

• Open syncope-console application and login as administrator (default installation: http://localhost:8080/syncope-console, credentials admin/password.)
• From the Dashboard menu, open Configuration, then Types.
• In the main panel, click on the Schemas tab (this is the first step, to add attributes to the Schema.)  We will use PLAIN schema here along with DERIVED.
  1. Expand PLAIN schema section (by clicking on 'PLAIN' text, should be open by default)
  2. Click on the PLUS sign to add a new attribute (an entry form pops up)
  3. Enter 'firstName' into the 'Key' field, leave 'Type' as string, no 'Validator class', let 'Mandatory' remain false other values not selected.  Save.
  4. Repeat (b) and (c) to add 'lastName'
  5. Expand DERIVED section and hit PLUS to add a new attribute
  6. Enter 'fullName' in the 'Key' field and firstName + ' ' + lastName in the 'Expression' field, hit SAVE.
• In the main panel, click on the AnyTypeClasses tab (this is the important second step to associate new schemas with the USER type.)
  1. Find an entry under key 'BaseUser', and hit the PENCIL button to the right to edit it.
  2. Select (highlight in Available list, hit the right-arrow button) firstName and lastName from Plain and fullName from Derived Schemas, then save.
• Now your user will have new fields.  You can check it by:
  1. Open Realms menu
  2. Click on USER tab
  3. Edit any existing user or create a new one
  4. When you get to the third page of the User wizzard, your new fields will be available to edit under Plain Attributes, and the Derived ones will be computed on the next page.

Via REST Request

• Create a file custom-schemas.json similar to the one attached below.  It includes a full list of attributes, not all are required.
• Note, that we will be creating fields First Name, Last Name and derived Full Name that is a combination of the two.
• Then, assuming your admin credentials are set to default, you are running in a BASH shell and have cURL installed, and syncope is running on http://localhost:8080, run the following script:

     SYNCOPE_BASE_URL=http://localhost:8080

     USER=admin

     PASS=password

     SCHEMA_FILE=custom-schema.json

     while read MSG

     do

       curl -v -X POST -u ${USER}:${PASS} \

               -H 'Content-Type: application/json' \
               -H 'Accept: application/json' \
               -H 'X-Syncope-Domain: Master' \
               --data "$MSG" \
               ${SYNCOPE_BASE_URL}/syncope/rest/schemas/PLAIN
     done < ${SCHEMA_FILE}

• The script will produce console output with HTTP return codes, which should all be 201.  
• Now your user will have new fields.  You can check then by:
  1. Open Realms menu
  2. Click on USER tab
  3. Edit any existing user or create a new one
  4. When you get to the third page of the User wizzard, your new fields will be available to edit under Plain Attributes, and the Derived ones will be computed on the next page.

custom-schemas.json