SCIM configuration basics
PingAuthorize Server’s System for Cross-domain Identity Management (SCIM) subsystem consists of the following components.
- SCIM resource types
-
SCIM resource types define a class of resources, such as users or devices. Every SCIM resource type features at least one SCIM schema, which defines the attributes and subattributes that are available to each resource, and at least one store adapter, which handles datastore interactions.
The following SCIM resource types differ according to the definitions of the SCIM schema:
-
Mapping SCIM resource type – Requires an explicitly defined SCIM schema, with explicitly defined mappings of SCIM attributes to store adapter attributes. Use a mapping SCIM resource type to exercise detailed control over the SCIM schema, its attributes, and its mappings.
-
Pass-through SCIM resource type – Does not use an explicitly defined SCIM schema. Instead, an implicit schema is generated dynamically, based on the schema that is reported by the store adapter. Use a pass-through SCIM resource type when you need to get started quickly.
-
- SCIM schemas
-
SCIM schemas define a collection of SCIM attributes, grouped under an identifier called a schema URN. Each SCIM resource type possesses a single core schema and can feature schema extensions, which act as secondary attribute groupings that the schema URN namespaces. SCIM schemas are defined independently of SCIM resource types, and multiple SCIM resource types can use a single SCIM schema as a core schema or schema extension.
A SCIM attribute defines an attribute that is available under a SCIM schema. The configuration for a SCIM attribute defines its data type, regardless of whether it is required, single-valued, or multi-valued. Because it consists of SCIM subattributes, a SCIM attribute can be defined as a complex attribute.
- Store adapters
-
Store adapters act as a bridge between PingAuthorize Server’s SCIM system and an external datastore. PingAuthorize Server provides a built-in LDAP store adapter to support LDAP datastores, including PingDirectory Server and PingDirectoryProxy Server. The LDAP store adapter uses a configurable load-balancing algorithm to spread the load among multiple directory servers. Use the Server SDK to create store adapters for arbitrary datastore types.
Each SCIM resource type features a primary store adapter and can also define multiple secondary store adapters. Secondary store adapters allow a single SCIM resource to consist of attributes retrieved from multiple datastores.
Store adapter mappings define the manner in which a SCIM resource type maps the attributes in its SCIM schemas to native attributes of the datastore.
About the create-initial-config tool
The create-initial-config
tool helps to quickly configure PingAuthorize Server for the System for Cross-domain Identity Management (SCIM).
Run this tool after completing setup to configure a SCIM resource type named Users
, along with a related configuration.
For an example of using create-initial-config
to create a pass-through SCIM resource type, see Configuring the PingAuthorize user store.
Example: Mapped SCIM resource type for devices
This example demonstrates the addition of a simple mapped SCIM resource type, backed by the standard device
object class of a PingDirectory Server.
To add data to PingDirectory Server, create a file named devices.ldif
with the following contents:
dn: ou=Devices,dc=example,dc=com objectClass: top objectClass: organizationalUnit ou: Devices dn: cn=device.0,ou=Devices,dc=example,dc=com objectClass: top objectClass: device cn: device.0 description: Description for device.0 dn: cn=device.1,ou=Devices,dc=example,dc=com objectClass: top objectClass: device cn: device.1 description: Description for device.1
Use the ldapmodify
tool to load the data file.
{pingdir}/bin/ldapmodify --defaultAdd --filename devices.ldif
Start configuring PingAuthorize Server by adding a store adapter.
dsconfig create-store-adapter \ --adapter-name DeviceStoreAdapter \ --type ldap \ --set enabled:true \ --set "load-balancing-algorithm:User Store LBA" \ --set structural-ldap-objectclass:device \ --set include-base-dn:ou=devices,dc=example,dc=com \ --set include-operational-attribute:createTimestamp \ --set include-operational-attribute:modifyTimestamp \ --set create-dn-pattern:entryUUID=server-generated,ou=devices,dc=example,dc=com
The previous command creates a store adapter that handles LDAP entries found under the base DN ou=devices,dc=example,dc=com
with the object class device
. This example uses the user store load-balancing algorithm that is created when you use the create-initial-config
tool to set up a users
SCIM resource type.
The following command creates a SCIM schema for devices with the schema URN urn:pingidentity:schemas:Device:1.0
:
dsconfig create-scim-schema \ --schema-name urn:pingidentity:schemas:Device:1.0 \ --set display-name:Device
Under this schema, add the string attributes name
and description
.
dsconfig create-scim-attribute \ --schema-name urn:pingidentity:schemas:Device:1.0 \ --attribute-name name \ --set required:true dsconfig create-scim-attribute \ --schema-name urn:pingidentity:schemas:Device:1.0 \ --attribute-name description
After you create a store adapter and schema, create the SCIM resource type.
dsconfig create-scim-resource-type \ --type-name Devices \ --type mapping \ --set enabled:true \ --set endpoint:Devices \ --set primary-store-adapter:DeviceStoreAdapter \ --set lookthrough-limit:500 \ --set core-schema:urn:pingidentity:schemas:Device:1.0
Map the two SCIM attributes to the corresponding LDAP attributes. The following commands map the SCIM name
attribute to the LDAP cn
attribute, and map the SCIM description
attribute to the LDAP description
attribute:
dsconfig create-store-adapter-mapping \ --type-name Devices \ --mapping-name name \ --set scim-resource-type-attribute:name \ --set store-adapter-attribute:cn \ --set searchable:true dsconfig create-store-adapter-mapping \ --type-name Devices \ --mapping-name description \ --set scim-resource-type-attribute:description \ --set store-adapter-attribute:description
To confirm that the new resource type has been added, send the following request to the SCIM resource types endpoint:
curl -k https://localhost:8443/scim/v2/ResourceTypes/Devices
The response is:
{"schemas":["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],"id":"Devices","name":
"Devices","endpoint":"Devices","schema":"urn:pingidentity:schemas:Device:1.0",
"meta":{"resourceType":"ResourceType","location":"https://localhost:8443/scim/v2/ResourceTypes/Devices"}}
For a more advanced example of a mapped SCIM resource type, see the example User schema in PingAuthorize/resource/starter-schemas
.