PingDirectory

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. After this has been 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.

<resource> element

A resource element has the following XML attributes:

  • schema: a required attribute specifying the SCIM schema URN for the resource. Standard SCIM resources already have URNs assigned for them, such as urn:scim:schemas:core:1.0. A new URN must be obtained for custom resources using any of the standard URN assignment methods.

  • name: a required attribute specifying the name of the resource used to access it through the SCIM REST API.

  • mapping: a custom Java class that provides the logic for the resource mapper. This class must extend the com.unboundid.scim.ldap.ResourceMapper class.

A resource element contains the following XML elements in sequence:

  • description: a required element describing the resource.

  • endpoint: a required element specifying the endpoint to access the resource using the SCIM REST API.

  • LDAPSearchRef: a mandatory element that points to an LDAPSearch element. The LDAPSearch element allows a SCIM query for the resource to be handled by an LDAP service and also specifies how the SCIM resource ID is mapped to the LDAP server.

  • LDAPAdd: an optional element specifying information to allow a new SCIM resource to be added through an LDAP service. If the element is not provided then new resources cannot be created through the SCIM service.

  • attribute: one or more elements specifying the SCIM attributes for the resource.

<attribute> element

An attribute element has the following XML attributes:

  • schema: a required attribute specifying the schema URN for the SCIM attribute. If omitted, the schema URN is assumed to be the same as that of the enclosing resource, so this only needs to be provided for SCIM extension attributes. Standard SCIM attributes already have URNs assigned for them, such as urn:scim:schemas:core:1.0. A new URN must be obtained for custom SCIM attributes using any of the standard URN assignment methods.

  • name: a required attribute specifying the name of the SCIM attribute.

  • readOnly: an optional attribute indicating whether the SCIM sub-attribute is not allowed to be updated by the SCIM service consumer. The default value is false.

  • required: an optional attribute indicating whether the SCIM attribute is required to be present in the resource. The default value is false.

An attribute element contains the following XML elements in sequence:

  • description: a required element describing the attribute. Then just one of the following elements:

  • simple: specifies a simple, singular SCIM attribute.

  • complex: specifies a complex, singular SCIM attribute.

  • simpleMultiValued: specifies a simple, multi-valued SCIM attribute.

  • complexMultiValued: specifies a complex, multi-valued SCIM attribute.

<simple> element

A simple element has the following XML attributes:

  • dataType: a required attribute specifying the simple data type for the SCIM attribute. The following values are permitted: binary, boolean, dateTime, decimal, integer, and string.

  • caseExact: an optional attribute that is only applicable for string data types. It indicates whether comparisons between two string values use a case-exact match or a case-ignore match. The default value is false.

A simple element contains the following XML element in sequence:

  • mapping: an optional element specifying a mapping between the SCIM attribute and an LDAP attribute. If this element is omitted, the SCIM attribute has no mapping and the SCIM service ignores any values provided for the SCIM attribute.

<complex> element

The complex element does not have any XML attributes. It contains the following XML element:

  • subAttribute: one or more elements specifying the sub-attributes of the complex SCIM attribute, and an optional mapping to LDAP. The standard type, primary, and display sub-attributes do not need to be specified.

<simpleMultiValued> element

A simpleMultiValued element has the following XML attributes:

  • childName: a required attribute specifying the name of the tag that is used to encode values of the SCIM attribute in XML in the REST API protocol. For example, the tag for the standard emails SCIM attribute is email.

  • dataType: a required attribute specifying the simple data type for the plural SCIM attribute (in other words, the data type for the value sub-attribute). The following values are permitted: binary, boolean, dateTime, integer, and string.

  • caseExact: an optional attribute that is only applicable for string data types. It indicates whether comparisons between two string values use a case-exact match or a case-ignore match. The default value is false.

A simpleMultiValued element contains the following XML elements in sequence:

  • canonicalValue: specifies the values of the type sub-attribute that is used to label each individual value, and an optional mapping to LDAP.

  • mapping: an optional element specifying a default mapping between the SCIM attribute and an LDAP attribute.

<complexMultiValued> element

A complexMultiValued element has the following XML attributes:

  • tag: a required attribute specifying the name of the tag that is used to encode values of the SCIM attribute in XML in the REST API protocol. For example, the tag for the standard addresses SCIM attribute is address.

A complexMultiValued element contains the following XML elements in sequence:

  • subAttribute: one or more elements specifying the sub-attributes of the complex SCIM attribute. The standard type, primary, and display sub-attributes do not need to be specified.

  • canonicalValue: specifies the values of the type sub-attribute that is used to label each individual value, and an optional mapping to LDAP.

<subAttribute> element

A subAttribute element has the following XML attributes:

  • name: a required element specifying the name of the sub-attribute.

  • readOnly: an optional attribute indicating whether the SCIM sub-attribute is not allowed to be updated by the SCIM service consumer. The default value is false.

  • required: an optional attribute indicating whether the SCIM sub-attribute is required to be present in the SCIM attribute. The default value is false.

  • dataType: a required attribute specifying the simple data type for the SCIM sub-attribute. The following values are permitted: binary, boolean, dateTime, integer, and string.

  • caseExact: an optional attribute that is only applicable for string data types. It indicates whether comparisons between two string values use a case-exact match or a case-ignore match. The default value is false.

A subAttribute element contains the following XML elements in sequence:

  • description: a required element describing the sub-attribute.

  • mapping: an optional element specifying a mapping between the SCIM sub-attribute and an LDAP attribute. This element is not applicable within the complexMultiValued element.

<canonicalValue> element

A canonicalValue element has the following XML attributes:

  • name: specifies the value of the type sub-attribute. For example, work is the value for emails, phone numbers, and addresses intended for business purposes.

A canonicalValue element contains the following XML element in sequence:

  • subMapping: an optional element specifying mappings for one or more of the sub-attributes. Any sub-attributes that have no mappings will be ignored by the mapping service.

<mapping> element

A mapping element has the following XML attributes:

  • ldapAttribute: a required element specifying the name of the LDAP attribute to which the SCIM attribute or sub-attribute map.

  • transform: an optional element specifying a transformation to apply when mapping an attribute value from SCIM to LDAP, and LDAP to SCIM. The available transformations are described in Map LDAP schema to SCIM resource schema.

<subMapping> element

A subMapping element has the following XML attributes:

  • name: a required element specifying the name of the sub-attribute that is mapped.

  • ldapAttribute: a required element specifying the name of the LDAP attribute to which the SCIM sub-attribute maps.

  • transform: an optional element specifying a transformation to apply when mapping an attribute value from SCIM to LDAP and vice-versa. The available transformations are described later. Available transformations are described in Map LDAP schema to SCIM resource schema.

<LDAPSearch> element

An LDAPSearch element has the following XML attributes:

  • baseDN: a required element specifying the LDAP search base DN to be used when querying for the SCIM resource.

  • filter: a required element specifying an LDAP filter that matches entries representing the SCIM resource. This filter is typically an equality filter on the LDAP object class.

  • resourceIDMapping: an optional element specifying a mapping from the SCIM resource ID to an LDAP attribute. When the element is omitted, the resource ID maps to the LDAP entry DN.

The LDAPSearch element can be added as a top-level element outside of any <Resource> elements, and then referenced within them with an ID attribute.

<resourceIDMapping> element

A resourceIDMapping element has the following XML attributes:

  • ldapAttribute: a required element specifying the name of the LDAP attribute to which the SCIM resource ID maps.

  • createdBy: a required element specifying the source of the resource ID value when a new resource is created by the SCIM consumer using a POST operation. Allowable values for this element include <scim-consumer>, meaning that a value must be present in the initial resource content provided by the SCIM consumer, or directory, (as would be the case if the mapped LDAP attribute is entryUUID).

If the LDAP attribute value is not listed as a destination correlation attribute, this setting is not used by PingDataSync.

The following example illustrates an LDAPSearch element that contains a resourceIDMapping element:

<LDAPSearch id="userSearchParams">
  <baseDN>ou=people,dc=example,dc=com</baseDN>
  <filter>(objectClass=inetOrgPerson)</filter>
  <resourceIDMapping ldapAttribute="entryUUID" createdBy="directory"/>
</LDAPSearch>

<LDAPAdd> element

An LDAPAdd element has the following XML attributes:

  • DNTemplate: a required element specifying a template that is used to construct the DN of an entry representing a SCIM resource when it is created. The template can reference values of the entry after it has been mapped using {ldapAttr}, where ldapAttr is the name of an LDAP attribute.

  • fixedAttribute: zero or more elements specifying fixed LDAP values to be inserted into the entry after it has been mapped from the SCIM resource.

<fixedAttribute> element

A fixedAttribute element has the following XML attributes:

  • ldapAttribute: a required attribute specifying the name of the LDAP attribute for the fixed values.

  • onConflict: an optional attribute specifying the behavior when the LDAP entry already contains the specified LDAP attribute. The default value merge indicates that the fixed values should be merged with the existing values. The value overwrite indicates that the existing values are to be overwritten by the fixed values. The value preserve indicates that no changes should be made.

A fixedAttribute element contains the following XML element:

  • fixedValue: one or more elements specifying the fixed LDAP values.