PingDirectory

Mapping the LDAP schema to the SCIM resource schema

The resources configuration file is an XML file that is used to define the SCIM resource schema and its mapping to LDAP schema. The default configuration of the scim-resources.xml file provides definitions for the standard SCIM Users and Groups resources, and mappings to the standard LDAP inetOrgPerson and groupOfUniqueNames object classes.

The default configuration 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.

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 DNs of the PingDirectory server, then a distinct SCIM resource must be defined for each unique entry location in the Directory Information Tree. This can be implemented in many ways. For example:

  • Create multiple SCIM servlets, each with a unique scim-resources.xml configuration, and each running under a unique HTTP connection handler.

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

Note that LDAP attributes are allowed to contain characters that are invalid in XML (because not all valid UTF-8 characters are valid XML characters). The easiest and most-correct way to handle this is to make sure that any attributes that might contain binary data are declared using "dataType=binary" in the scim-resources.xml file. Likewise, when using the Identity Access API make sure that the underlying LDAP schema uses the Binary or Octet String attribute syntax for attributes that might contain binary data. This will cause the server to automatically base64-encode the data before returning it to clients and will also make it predictable for clients because they can assume the data will always be base64-encoded.

However, it is still possible that attributes that are not declared as binary in the schema might contain binary data (or just data that is invalid in XML), and the server will always 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 which are found to 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 scim-resources.xml file.