PingDirectory

Configuring an identity mapper

The Consent Service uses identity mappers to map requester identities, subject values, and actor values to distinguished names (DNs).

An identity mapper takes a user identifier string and correlates the identifier with the DN of a user entry. The PingDirectory server provides four different types of identity mappers.

Identity mapper types and descriptions
Identity mapper type Description

Exact match identity mapper

Maps a user identifier to a DN by searching for an entry with an attribute that exactly matches the identifier.

Regular expression identity mapper

Similar to an exact match identity mapper, but allows a regular expression to be specified for more flexible matching.

Third-party identity mapper

A custom Java identity mapper implementation written using the Server SDK.

Groovy scripted identity mapper

A custom Groovy identity mapper implementation written using the Server SDK.

The Consent Service can be configured to use identity mappers for each of the following scenarios:

Requesters authenticating using basic authentication

Use the Consent HTTP Servlet Extension identity-mapper property to configure an identity mapper that takes the HTTP Basic authorization user name string to find the corresponding user’s identity in the PingDirectory server.

Requesters authenticating using bearer token authentication

Use the Access Token Validator identity-mapper property to configure an identity mapper that takes the subject or other claim value from the OAuth token to find the corresponding user’s identity in the PingDirectory server.

Consent record actor and subject values

Use the Consent Service consent-record-identity-mapper property to configure an identity mapper that takes these consent record attribute values and uses them to find the corresponding users' identities in the PingDirectory server.

By default, the Consent Service sets the subject, subjectDN, actor, and actorDN values to the identity of the authenticated requester. If the requester uses basic authentication, then all values are set to the auth DN determined by the basic authentication identity mapper. If the requester uses bearer token authentication, then the subject and actor values are set to the bearer token’s subject claim value, while the subjectDN and actorDN values are set to the auth DN determined by the access token validator identity mapper.

Privileged clients can manually set a consent record’s subject and actor values. In those cases, the Consent Service’s consent-record-identity-mapper property is used to map a consent record’s subject and actor values to subjectDN and actorDN values, respectively.

Identity mapper configuration options

The Consent Service configuration script configures a single identity mapper to be used for all three scenarios. The provided identity mapper searches by uid, cn, or entryUUID attributes under the base DNs cn=config and ou=people,dc=example,dc=com.

The following configuration provides an example of an identity mapper that matches a user identifier to an Lightweight Directory Access Protocol (LDAP) entry with the same value in its uid attribute.

$ bin/dsconfig create-identity-mapper --mapper-name "User ID Exact Match" \
  --type exact-match \
  --set enabled:true \
  --set match-attribute:uid

This configuration shows another typical example: an identity mapper that matches a user identifier to an LDAP entry with the same value in its entryUUID attribute.

$ bin/dsconfig create-identity-mapper --mapper-name "EntryUUID Exact Match" \
  --type exact-match \
  --set enabled:true \
  --set match-attribute:entryUUID

This final example creates an identity mapper that matches a user identifier to an LDAP entry with the same value in either its uid, cn, or entryUUID attribute. This identity mapper also constrains its search to the cn=config and ou=people,dc=example,dc=com and cn=config base DNs. By default, the cn=config base DN is not searched and must be explicitly listed to be searched.

$ bin/dsconfig create-identity-mapper \
  --mapper-name "User ID Identity Mapper" \
  --type exact-match \
  --set enabled:true \
  --set match-attribute:uid \
  --set match-attribute:cn \
  --set match-attribute:entryUUID \
  --set match-base-dn:cn=config \
  --set match-base-dn:ou=people,dc=example,dc=com