The System for Cross-domain Identity Management (SCIM) specification automates user identity management between identity domains. This chapter describes the configuration of the RadiantOne SCIM service. The RadiantOne service supports SCIMv2.

For the RadiantOne service to support SCIM queries from clients, a SCIM schema and resource type are required. To access the SCIM configuration in the Main Control Panel, go to Settings Tab > Server Front End > SCIM. The SCIM Configuration page contains three sub tabs: Schemas, Resource Types, and Preview.

Figure 1: SCIM Configuration

The configuration is saved in: <RLI_HOME>/vds_server/conf/scim2. This folder contains three sub-folders: resources, schemas, and templates. The resources folder contains all resource type definitions, each defined in a JSON-formatted file. The schemas folder contains a definition for attributes, each defined in a JSON-formatted file. The templates folder contains predefined attribute mappings.

Quick Start Configuration

To configure SCIM access to RadiantOne entries you can use the Quick Start option to automatically define a SCIM schema and resource type that matches the objects and attributes associated with your entries, or you can define your own SCIM schema and resource type. This example describes the Quick Start steps. See Creating Schemas and Creating Resource Types for steps on customizing your own.

1. Create a virtual view of your identity sources. There are many methods to create virtual views using RadiantOne. If you need assistance, see the RadiantOne Namespace Configuration Guide, Context Builder Guide, and the Identity Service Wizards Guide. If your identities are in a RadiantOne Universal Directory instead of a virtual view, make sure you know what object class they are associated with.
2. If using a virtual view, make sure it is mounted below a Root Naming Context in the RadiantOne namespace. If you need assistance, see the RadiantOne Namespace Configuration Guide.
3. If the identities are associated with custom object classes or attributes (not currently defined in the RadiantOne schema), extend the RadiantOne schema with the objects and attributes. If you need assistance, see Chapter 4 in the RadiantOne System Administration Guide.
4. Go to the Main Control Panel > Settings Tab > Server Front End > SCIM.
5. In the SCIM Configuration, click Quick Start.
6. Enter a unique name in the Name property. This is used as the name for the Resource Type.
7. For the Endpoint, enter an endpoint identifier. This comprises the URL a SCIM client uses to access the entries.
8. For the Base DN, click Browse and select the root naming context in the RadiantOne namespace where your virtual view is mounted.
9. For the Primary Object Class, select the object class associated with the identities in the virtual view from the drop-down list. If you do not see your object class here, extend the RadiantOne schema prior to using this Quick Start. See Chapter 4 in the RadiantOne System Administration Guide.
10. Click Save. An example is shown below.

Figure 2: SCIM Quick Start

1. To view the attribute mappings that were auto-generated, select the Resource Types tab.
2. Select the resource type name you configured and click the MAPPINGS tab. An example is shown below.

Figure 3: Example of Auto-generated Attribute Mappings

1. Click the Preview tab and select the Resource Type from the drop-down list.
2. Click Send. The entries in the RadiantOne service are returned as SCIM entries.

Figure 4: SCIM Preview Tab

A SCIM schema designates attribute characteristics such as their mutability, type, and other features. The core SCIM schemas: User, Group, and Enterprise User Extensions are supported and configured by default in RadiantOne. Custom schemas are also supported. SCIM schemas are managed from the Main Control Panel > Settings Tab > Server Front End > SCIM section -> Schemas tab on the right.

To query the SCIM schema (core, extension and custom) in the RadiantOne service, a SCIM client can use: http://<RadiantOneService>:8089/scim2/v2/Schemas

Group Default Core Schema

To view the default Group SCIM schema, go to the Main Control Panel > Settings Tab > Server Front End > SCIM. On the Schemas tab, click Group. The default attributes are outlined in the table below.

Table 1: SCIM Attributes Associated with the Default Group Schema

User Default Core Schema

To view the default User SCIM schema, go to the Main Control Panel > Settings Tab > Server Front End > SCIM. On the Schemas tab, click User. The default attributes are outlined in the table below.

Table 2: SCIM Attributes Associated with the Default User Schema

Enterprise User Default Core Schema

To view the default Enterprise User SCIM schema, go to the Main Control Panel > Settings Tab > Server Front End > SCIM. On the Schemas tab, click User. The default attributes are outlined in the table below.

Table 3: SCIM Attributes Associated with the Default Enterprise User Schema

If the default SCIM schemas do not meet your needs, you can create a new one.

To add a new schema:

1. From the Main Control Panel, click the Settings Tab > Server Front End section > SCIM sub-section.

2. Click New Schema.

3. Enter the Schema URN (Uniform Resource Name). This value must be unique.

4. Enter a unique display name.

5. To add attributes to the schema, click the New Attribute button. For more information, see the Custom SCIM Attributes section.

6. Click Save.

Custom SCIM Attributes

Custom SCIM attributes can be created for new schemas or when editing existing custom schemas.

Attributes can be either single-valued or multi-valued. Multi-valued attributes like email, phoneNumbers, and ims can support canonical values, like Type (work, home, mobile, fax, pager…etc.). SCIM also supports complex attributes where an attribute can have sub-attributes. This section describes the attribute types and provides an example for each.

Simple, single-valued attribute – an attribute that contains a single value.

{
  "displayName" : "Carmen, Brian"
}
Simple, multi-valued attribute – an attribute that contains multiple values. These attributes can include a canonical “type” attribute to indicate the type of value specified.
{
  "emails" : [
  {
    "type" : "other",
    "value" : "[email protected]"
  },
  {
    "type" : "work",
    "value" : "[email protected]"
  }]
}

Complex attribute – an attribute that contains one or more simple attributes as sub-attributes.

{
  "name" : {
    "familyName" : "Carmen",
    "givenName" : "Brian",
    "displayName" : "Carmen, Brian" }
}

“givenName” is a sub-attribute of the “name” complex attribute.

To create SCIM attributes:

1. From the Main Control Panel, click the Settings Tab > Server Front End > SCIM > Schemas tab on the right.

2. On the Schemas tab, either create a new schema or click and existing schema.

3. Click the New Attribute button.

4. Name the attribute.

5. Provide an optional description.

6. Select an attribute type.

7. Enable the Required option if you want this attribute to be required (have a value) to insert or update entries associated with this SCIM schema.

8. Enable the Multi-valued option if the attribute will have more than one value associated with it. Both simple and complex attributes can be multi-valued.

9. Enable Case Exact if the attribute is a string type and you want the value to be case-sensitive.

10. Select the mutability.

11. Select the condition in which the attribute is returned. This indicates when an attribute and associated values are returned in response to a GET request or in response to a PUT, POST, or PATCH request.

12. Click Save.

13. Repeat steps 3-12 to add all attributes.

SCIM Attribute Types

Table 4: Attribute Types

SCIM Attribute Mutability

Each custom attribute has a mutability property that dictates how the RadiantOne service handles the attribute when processing operations. The possible values (and meaning) for the mutability property are summarized in the table below.

Table 5: Attribute Mutability

SCIM Attribute Returned Characteristics

Each attribute has a characteristic regarding the behavior of how it is returned to clients. The possible values (and meaning) for the Returned property are summarized in the table below.

Table 6: Attribute Returned Characteristics

If you have an existing schema definition (JSON-formatted), you can import this into the RadiantOne configuration. To import a schema:

1. From the Main Control Panel, click the Settings Tab > Server Front End section > SCIM sub-section.

2. Click the Import Schema button.

3. In the Import Schema window, click the Choose File button.

4. Navigate to the directory containing the schema file. Select the file and click Open.

5. Click Import.

To delete a schema:

1. From the Main Control Panel, click the Settings Tab > Server Front End section > SCIM sub-section.

2. Click the checkbox of the schema to be deleted.

3. Click Delete.

4. In the confirmation window, click Confirm.

SCIM resource types are managed from the Main Control Panel > Settings Tab > Server Front End > SCIM section > Resource Types tab on the right.

A SCIM resource type is a collection of SCIM attributes identified by one or more SCIM schemas. Resource types are associated with specific base DNs in the RadiantOne namespace. For example, the “Users” resource type could be associated with o=companydirectory. This means that resource type “Users” cannot be associated with any other base DN. If you want to associate a resource type to multiple base DNs/views, you must aggregate them under a common root naming context and associate the resource type with the root naming context level.

The Base DN configured for the resource type dictates what root naming context the query applies to. If you want to find multiple resource types in the same base DN, you must create a resource type for each with a specific primary object class and unique endpoint name. For example, if you want to find both users and groups in o=companydirectory, you would create a resource type using the inetOrgPerson primary object class. You would then create another resource type using the groupOfUniqueNames object class.

Resource types are linked to a core SCIM schema and an optional set of extension schemas. Attribute mappings (between attributes in the virtual view to SCIM) can be applied across one or more SCIM schemas and a single virtual attribute can be mapped to more than one SCIM attribute.

To add a new resource type:

1. From the Main Control Panel, click the Settings Tab > Server Front End section > SCIM sub-section.

2. Click the Resource Types tab.

3. Click the New Resource Type button.

4. On the Config page, enter a unique name to identify the resource.

5. Enter the suffix of the SCIM URL to associate with this resource type in the Endpoint property. (e.g. MyUsers)

6. To enable the resource type, click the Active toggle switch.

7. (Optional) Enter a description of the resource in the Description property.

8. Click Browse next to the Base DN property and select the root naming context in the RadiantOne namespace where the identities (e.g. users and groups) that you want accessible with SCIM are located.

9. (Optional) Define a DN Pattern using regular expression(s). This set of regular expressions is used to determine the Resource Type of a given entry, based on that entry's full DN. Any entry that has a DN that fully matches one of these regular expressions will be associated with this Resource Type. In the example shown below, only entries that start with “cn=” located in any “ou=” container below o=companydirectory or entries that start with “uid=” located below “ou=Employees,o=companydirectory” will be associated with this resource type.

10. (Optional) Enter an LDAP filter if you want to condition the entries returned by the search.

11. Enter the maximum number of entries to return in a query in the Max Entries Returned property.

12. Enter the Primary Object Class associated with your identities. This is the object class associated with the identities in your virtual view and/or Universal Directory store. This and the auxiliary object class(es) property determine which attributes are available to map to the SCIM schema.

13. (Optional) Enter additional [auxiliary] object class(es) associated with the identities in your virtual view and/or Universal Directory store. This and the primary object class determine which attributes are available to map to the SCIM schema. This drop-down menu allows the selection of multiple items.

14. Enter a DN Expression to calculate the LDAP DN for new entries. If the SCIM URL in the POST request does not specify the DN of the entry to insert, this property dictates how attribute value(s) from the body of the request are used to generate the DN for the new entry (e.g. uid=${userName},o=companydirectory). This DN expression should mimic the root naming context in the RadiantOne namespace where you want new entries created, prefixed with the RDN name and SCIM attribute in curly braces used to populate the RDN value.

15. Select the core SCIM schema to associate with the resource type from the SCIM Core Schema drop-down list.

16. (Optional) Select required (extension) schemas from the table on the left. To add all items as required schemas, click the button. To add selected items as required schemas, select schemas from the table on the left and click the button.

17. (Optional) Select optional schemas from the table on the left. To add all choices as optional schemas, click the button. To add only selected items as optional schemas, select schemas from the table on the left and click the button.

18. Click Next. The Mappings page is displayed.

19. Map LDAP attributes in your RadiantOne virtual view or Universal Directory store to SCIM attributes using either a pre-defined template or a manual mapping.

20. Click the Save button. The SCIM Configuration page displays the configured resource.

Template-based Attribute Mapping

To use a pre-defined template for attribute mapping, click the Load Template button.

The templates are pre-defined mappings based on object class and the schema URN. If the object class and schema URN of the resource type being created matches that of an existing resource(s), the relevant mapping template(s) are listed with multi-select checkboxes, as shown in the following image.

Figure 5: Applying a Template

If no match is detected, a drop-down menu allows you to select one of the following templates.

Figure 6: Selecting a Template

To remove a mapping, click the button in the LDAP Attribute column in the table on the right.

Manual Attribute Mapping

To manually define an attribute mapping, select an attribute in the table on the left. In the table on the right, click the corresponding SCIM attribute, and click the button. Repeat this process for all attributes to be mapped.

To remove a mapping, click the button in the LDAP Attribute column in the table on the right.

Mapping Complex Attributes

A complex attribute is a singular or multi-valued attribute whose value is a composition of one or more simple attributes (sub-attributes). A complex attribute may be mapped, or its sub-attributes may be mapped, but not both. To manually map a complex attribute, select an attribute in the table on the left. In the table on the right, click the corresponding SCIM attribute, and click the button.

To map a complex attribute’s sub-attribute(s):

1. Select an attribute in the table on the left.

2. In the table on the right, click Plus-sign next to the complex SCIM attribute. The complex attribute is hidden, and its sub-attributes are displayed.

Figure 7: Expanding a Complex Attribute

3. In the table on the right, click the corresponding SCIM sub-attribute, and click the button.

In the following example, the sub-attributes of the complex attribute Office are mapped.

Figure 8: Mapping Sub-attributes

4. Click Save.

To collapse a complex attribute, click next to the topmost sub-attribute.

If you have an existing resource type definition (JSON-formatted), you can import this into the RadiantOne configuration.

To import a resource type:

1. From the Main Control Panel, click the Settings Tab > Server Front End > SCIM > Resource Types tab on the right.

2. Click Import Resource Type.

3. Click Choose File and navigate to the folder containing the schema file, select the file, and click Open.

4. Click the Import button.

To delete a resource:

1. From the Main Control Panel, click the Settings Tab > Server Front End > SCIM.

2. On the SCIM2 Configuration page, click the Resource Types tab.

3. Click the checkbox of the resource to be deleted.

4. Click Delete.

5. In the confirmation window, click Confirm.

To list all SCIM resource types configured in RadiantOne, use:

http://<RadiantOneService>:8089/scim2/v2/resourcetypes

Examples of SCIM clients used in this guide are WizTools.org REST Client and Postman. Some important items to keep in mind are listed below:

• Account creation uses POST. The DN expression (suffix) configured for the resource type indicates where the entry is created in the RadiantOne namespace. This account must not already exist.

• Mass attribute updates can be done with PUT. If you want to do a lot of changes on an entry, then it is generally easier to “replace” the whole entry. To do this, you can use PUT. PUT is similar to POST, except that the entry needs to already exist when using PUT. If the URL does not specify the DN of the entry to replace, the DN expression property configured for the resource type dictates how the ID attribute value from the body of the request is used to generate the DN.

• Entry deletion uses DELETE with URL containing the DN of the entry to delete.

• Add the “authorization” header with a value matching your RadiantOne user DN and password for authentication.

• Add the “Content-Type” header with a value of application/json.

• All keywords for Resource Types (v2/Users, v2/Groups, v2/List) in the SCIM request are case sensitive.

SCIM Operations Supported

Table 7: SCIM Operations Supported

SCIM Response Status Codes

One of these codes is an HTTP status returned to SCIM clients. (In the Response section of the REST client, look for the numeric value that follows "httpStatus"). The following table describes these HTTP status codes.

Table 8: SCIM Response Status Codes

Authentication

Authentication can be performed using basic authentication by passing the credentials in a header.

The header must be named “authorization” and the value is set by concatenating: Basic base64(dn:password). Don’t forget to use a between Basic and the encoded value. Don’t forget to use “:” to separate dn value from password value. You can use any base64 encoder to get this value. An example for cn=directory manager and password of secretsecret would be this: cn=directory manager:secretsecret

The base64 encoded value of this would be: Y249ZGlyZWN0b3J5IG1hbmFnZXI6c2VjcmV0c2VjcmV0

Resulting in a header of: <header key="authorization" value="Basic Y249ZGlyZWN0b3J5IG1hbmFnZXI6c2VjcmV0c2VjcmV0"/>

Below are some example SCIM requests using a Postman client.

Insert User

The following example creates an entry for a user named Barbara Jensen in one of the default RadiantOne Universal Directory stores located at o=companydirectory.

The resource type configuration and attribute mappings used in this example are shown below.

Figure 9: Resource Type Example

Figure 10: Sample Attribute Mappings

Based on the above configuration, the following is a sample SCIM POST query to create a user.

The following body example can be used to insert a user:

{
 "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User"
 ],
 "userName": "[email protected]",
 "name": {
   "formatted": "Ms. Barbara J Jensen, III",
   "familyName": "Jensen",
   "givenName": "Barbara",
   "middleName": "Jane"
 },
 "displayName": "Babs Jensen",
 "title": "Tour Guide",
 "userType": "Employee",
 "preferredLanguage": "en-US",
 "password": "t1meMa$heen",
 "emails": [
   {
     "value": "[email protected]",
     "type": "work",
     "primary": "true"
   }
 ],
 "phoneNumbers": [
   {
     "value": "555-555-5555",
     "type": "work"
   }
 ],
   "addresses": [
   {
     "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
     "streetAddress": "100 Universal City Plaza",
     "locality": "Hollywood",
     "region": "CA",
     "postalCode": "91608",
     "type": "work"
   }
 ]
 }

Table 8: SCIM Post Query to Create A User

Figure 11: POST Query to SCIMv2 API of RadiantOne

Based on the New Entry DN Expression in the Resource Type configuration described above, the entry is created as uid=[email protected],o=companydirectory. This can be seen in the RadiantOne in the screen shot below.

Figure 12: Sample Entry Created with a SCIM POST Operation

Insert User with Enterprise Extension Attributes

The following SCIM POST query example describes how to create a user entry that contains enterprise extension attributes like employeeNumber, division, and department. This example is based on the configuration described in the Insert Entry example above.

The following body example can be used to insert a user containing enterprise extension attributes:

 {
    "schemas": [
        "urn:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"       
    ],    
    "userName": "Acooper",
    "name": {
        "familyName": "Cooper",
        "givenName": "Alice in wonderland",
        "formatted": "Alice D Cooper"
    },
    "emails": [{
        "value": "[email protected]",
        "type": "work",
        "primary": true
    }],
    "title": "Song writer",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User":
    {
        "employeeNumber":"9252",
        "division":"Sales",
        "department": "Rock'n roll"
    }
}

Table 9: SCIM POST Query to Insert A User with Enterprise Extension Attributes

Figure 13: Example POST Query Shown in Postman

Based on the New Entry DN Expression in the Resource Type configuration described above, the entry is created as uid=Acooper,o=companydirectory. This can be seen in the RadiantOne in the screen shot below.

Figure 14: Sample Entry Created with a SCIM POST Operation

Update (PATCH) User

The following example updates an entry for a user named Barbara Jensen in one of the default RadiantOne Universal Directory stores located at o=companydirectory.

The resource type configuration and attribute mappings used in this example are shown below.

Figure 15: Resource Type Configuration Example

Figure 16: Sample Attribute Mappings

Based on the above configuration, the following is a sample SCIM PATCH query to update a user.

The following body example can be used to update a user:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "value": {
        "name": {
          "familyName": "Blake",
          "givenName": "Daphne"
        }
      }
    }
  ]
}

Table 10: SCIM PATCH Query to Update A User

Figure 17: PATCH Query to SCIMv2 API of RadiantOne

Based on the PATCH request described above, the entry uid=[email protected],o=companydirectory is updated. This can be seen in the RadiantOne in the screen below.

Figure 18: Sample Entry Updated with a SCIM PATCH Operation

Update (PUT) User with Enterprise Extension Attributes

The following SCIM PUT query example describes how to update a user entry that contains enterprise extension attributes like employeeNumber, division, and department. This example is based on the configuration described in the Insert Entry example above.

The following body example can be used to update a user containing enterprise extension attributes:

{
    "schemas": ["urn:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"       
    ],    
    "userName": "[email protected]",
    "name": {
        "familyName": "Jones",
        "givenName": "Barbara",
        "formatted": "Jones, Barbara"
    },
    "emails": [{
        "value": "[email protected]",
        "type": "work",
        "primary": true
    }],
    "title": "Hobbyist",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User":
    {
        "employeeNumber":"9252",
        "division":"Sales",
        "department": "Hobby"
    }
   }

Table 11: SCIM PUT Query to Update A User with Enterprise Extension Attributes

The PUT request from a Postman client is shown below.

Figure 19: Example SCIMv2 PUT Request

Based on the PUT request described above, the entry uid=[email protected],o=companydirectory is updated. This can be seen in RadiantOne in the screen shot below.

Figure 20: Sample Entry Updated with a SCIM PUT Operation  

Get Entry

The following SCIM GET query example describes how to retrieve the entry that was created in the Insert Entry example above.

Table 12: SCIM GET Query to Retrieve an Entry

The GET request from a Postman client is shown below.

Figure 21: SCIM GET Query Example

Delete Entry

The following SCIM DELETE query example describes how to delete the entry that was created in the Insert Entry example above.

Table 12: SCIM DELETE Query to Delete an Entry

The DELETE request from a Postman client is shown below.

Figure 22: SCIM DELETE Query Example