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 eid
attribute) 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 scimID
value 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 |
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 asurn: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 thecom.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 anLDAPSearch
element. TheLDAPSearch
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 asurn: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 isfalse
. -
required
: an optional attribute indicating whether the SCIM attribute is required to be present in the resource. The default value isfalse
.
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
, andstring
. -
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 isfalse
.
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
, andstring
. -
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 isfalse
.
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 standardaddresses
SCIM attribute isaddress
.
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 standardtype
,primary
, anddisplay
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 isfalse
. -
required
: an optional attribute indicating whether the SCIM sub-attribute is required to be present in the SCIM attribute. The default value isfalse
. -
dataType
: a required attribute specifying the simple data type for the SCIM sub-attribute. The following values are permitted:binary
,boolean
,dateTime
,integer
, andstring
. -
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 isfalse
.
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 thecomplexMultiValued
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 |
<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 isentryUUID
).
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}
, whereldapAttr
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 valuemerge
indicates that the fixed values should be merged with the existing values. The valueoverwrite
indicates that the existing values are to be overwritten by the fixed values. The valuepreserve
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.