Mapping OAuth attributes is a two-stage processing workflows:

  • The first stage: map from authentication sources (IdP adapter instances or IdP connections), authentication policy contracts, or Password Credential Validator instances (for resource owner credentials) to persistent grants.
  • The second stage: map from persistent grants (and optionally authentication sources, authentication policy contracts, authentication context, or Password Credential Validator instances) to access tokens.

Note that this two-stage mapping workflow is different from other mapping scenarios in PingFederate, which involve just a one-phase configuration.

Mapping OAuth attributes

The first stage

To accomplish the first stage, mapping is required for setting up persistent grants, including a user key and all extended attributes.

The mappings may use attributes obtained during initial authentication events within PingFederate, namely attributes from IdP adapter instances, attributes from assertions via IdP connections, attributes from authentication policy contracts, or attributes returned by password credential validator instances. Moreover, datastore queries may also be configured; for example, to retrieve the user identifier from an LDAP directory server as the user key.


The USER_KEY attribute values must be unique across all end users because the USER_KEY attribute is the user identifier to store and to retrieve persistent grants. For example, if you have two Active Directory domains, the sAMAccountName attribute value of an end user in one domain may collide with that of another end user in the other domain. In this scenario, you can map the Subject DN attribute to the USER_KEY attribute.

The second stage

The second mapping configuration involves mapping from persistent grants (the user keys, any extended attributes derived from the first stage, or both) into OAuth access tokens.

You may also set up specific mappings between the authentication sources, authentication policy contracts, or password credential validators. When the authentication context matches a specific mapping, attributes from the authentication sources, authentication policy contracts, or password credential validators can be mapped into the access tokens. Additionally, you can use an expression to retrieve from the HTTP Request Java object the authentication method that a client uses (or the private key JWT with which a client authenticates if the client uses the private_key_jwt authentication method) and then map it into the access tokens.

Data stores may also be used here to retrieve any required user attributes.

Runtime processing

At runtime, the first time a client requests an OAuth token the two mapping sequences are employed sequentially. The second mapping is invoked every time a new access token is requested based on an existing persistent grant.