---
title: Configuring an identity mapper
description: The Consent Service uses identity mappers to map requester identities, subject values, and actor values to distinguished names (DNs).
component: pingdirectory
version: 11.0
page_id: pingdirectory:consent_solution_guide:pd_cs_config_identity_mapper
canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/consent_solution_guide/pd_cs_config_identity_mapper.html
revdate: September 13, 2023
section_ids:
  the-consent-record-identity-mapper: The consent record identity mapper
  identity-mapper-configuration-options: Identity mapper configuration options
---

# 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.

## The consent record identity mapper

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 *(tooltip: \<div class="paragraph">
\<p>A data object by which a client authenticates to a resource server and lays claim to authorizations for accessing particular resources.\</p>
\</div>)* 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) *(tooltip: \<div class="paragraph">
\<p>An open, cross platform protocol used for interacting with directory services.\</p>
\</div>)* entry with the same value in its `uid` attribute.

```shell
$ 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.

```shell
$ 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.

```shell
$ 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
```