SCIM

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. The SCIM configuration is accessed in the Classic Control Panel.

Classic Control Panel

Open Classic Control Panel from the logged in user icon drop-down in the upper right corner:

In the Classic Control Panel, go to Settings Tab > Server Front End > SCIM. The SCIM Configuration page contains three sub tabs: Schemas, Resource Types, and Preview.

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. If your identities are in a RadiantOne Directory instead of a virtual view, make sure you know what object class they are associated with.

2. 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.

3. Go to the Classic Control Panel > Settings Tab > Server Front End > SCIM.

4. In the SCIM Configuration, click Quick Start.

5. Enter a unique name in the Name property. This is used as the name for the Resource Type.

6. For the Endpoint, enter an endpoint identifier. This comprises the URL a SCIM client uses to access the entries.

7. For the Base DN, click Browse and select the root naming context in the RadiantOne namespace where your virtual view is mounted.

8. 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.

9. Click Save. An example is shown below.

11. To view the attribute mappings that were auto-generated, select the Resource Types tab.

12. Select the resource type name you configured and click the MAPPINGS tab. An example is shown below.

13. Click the Preview tab and select the Resource Type from the drop-down list.

14. Click Send. The entries in the RadiantOne service are returned as SCIM entries.

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 Classic 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://<RadiantOneServiceEndpoint>/scim2/v2/Schemas

Group - Default Core Schema

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

User

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.

Enterprise User

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

Table 4.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 Classic Control Panel, click the Settings Tab > Server Front End section > SCIM sub-section.

2. Click the New Schema button.

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 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 Classic 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.

Attribute Types

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.

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.

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

1. From the Classic 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 the Import button.

To delete a schema:

1. From the Classic 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 the Delete button.

4. In the confirmation window, click Confirm.

SCIM resource types are managed from the Classic 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.

Creating Resource Types

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) Enter an LDAP filter if you want to condition the entries returned by the search.

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

11. 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.

12. (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.

13. 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.

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

15. (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.

16. (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.

17. Click Next. The Mappings page is displayed.

18. 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.

19. 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

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.

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 4.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.

Importing Resource Types

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.

Deleting Resource Types

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 the Delete button.
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 7: 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 <space> 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:

 {
  "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"
    }
  ]
  }

{
    "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"
    }
}

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

  {
    "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"
    }
   }