Map LDAP schema to SCIM resource schema

The resources configuration file is used to define the System for Cross-domain Identity Management (SCIM) resource schema and its mapping to Lightweight Directory Access Protocol (LDAP) schema. The default configuration of the scim-resources.xml file provides definitions for standard SCIM Users and Groups resources, and mappings to standard LDAP inetOrgPerson and groupOfUniqueNames object classes. It is installed with the PingDirectory server. This file can be customized by adding extension attributes to the Users and Groups resources, or by adding new extension resources. The resources file is composed of a single <resources> element, containing one or more <resource> elements.

The default configuration maps the SCIM resource ID to the LDAP entryUUID attribute. In all cases, this must be changed to match the attribute that the destination SCIM service provider is using for its SCIM resource ID. For example, if the destination uses the value of the uid attribute, modify the scim-resources.xml file to change the resourceIDMapping as follows:

<resourceIDMapping ldapAttribute="uid"/>

Ideally, this would be an attribute that exists on the source LDAP entry. If not, PingDataSync can construct it using a Constructed Attribute Mapping. For example, the SCIM service provider used the first and last initials of the user, concatenated with the employee ID (given by the eidattribute)as the SCIM resource ID. In this case, an attribute mapping would be constructed as follows:

$ dsconfig create-attribute-mapping \
  --map-name MyAttrMap \
  --mapping-name scimID \
  --type constructed \
  --set 'value-pattern:{givenname:/^(.)(.*)/$1/s}{sn:/^(.)(.*)/$1/s}{eid}'

This creates an attribute called scimID on the mapped entry when processed by the Sync engine. For example, if the user’s name was John Smith, with employee ID 12345, then the scimID would be js12345. Once this is done, configure the scim-resources.xml file as follows:

<resourceIDMapping ldapAttribute="scimID" />

This will cause it to pull out the constructed scimIDvalue from the entry and use that at the SCIM resource ID when making requests to the service provider.

Constructed attribute mappings support multivalued source attributes for conditional (using the conditional-value-pattern property) and non-conditional (using the value-pattern property) value patterns. Only one of the source attributes that contribute to a given value pattern can be multivalued.

For any given SCIM resource endpoint, only one <LDAPAdd> template can be defined, and only one <LDAPSearch> element can be referenced. If entries of the same object class can be located under different subtrees or base distinguished name (DN)s of the PingDirectory server, then a distinct SCIM resource must be defined for each unique entry location in the Directory Information Tree. If using the SCIM HTTP Servlet Extension for the PingDirectory server, this can be implemented in many ways, such as:

Create multiple SCIM servlets, each with a unique resources.xml configuration, and each running under a unique HTTP connection handler.
Create multiple SCIM servlets, each with a unique resources.xml configuration, each running under a single, shared HTTP connection handler, but each with a unique context path.

LDAP attributes are allowed to contain characters that are invalid in XML (because not all valid UTF-8 characters are valid XML characters). Make sure that any attributes that contain binary data are declared using dataType=binary in the scim-resources.xml file. When using the Identity Access API, make sure that the underlying LDAP schema uses the Binary or Octet String attribute syntax for attributes that contain binary data. This instructs the server to base64-encode the data before returning it to clients.

If attributes that are not declared as binary in the schema and contain binary data (or just data that is invalid in XML), the server will check for this before returning them to the client. If the client has set the content-type to XML, then the server can choose to base64-encode any values that include invalid XML characters. When this is done, a special attribute is added to the XML element to alert the client that the value is base64-encoded. For example:

<scim:value base64Encoded="true">AAABPB0EBZc=</scim:value>

The remainder of this section describes the mapping elements available in the scimresources.xml file.