The two stages of mapping OAuth attributes include:

  • The first stage: map from authentication sources, such as 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, authentication sources, authentication policy contracts, authentication context, or Password Credential Validator instances to access tokens.
Note:

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

Diagram showing the two stages of mapping OAuth attributes. The first stage: map from authentication sources, authentication policy contracts or PCVs to persistent grants. The second stage: map from persistent grants to access tokens.

The first stage

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

The mappings use attributes obtained during initial authentication events within PingFederate, namely attributes from IdP adapter instances, attributes from assertions through IdP connections, attributes from authentication policy contracts, or attributes returned by password credential validator instances. Configure data store queries to accomplish different tasks, such as retrieving the user identifier from an LDAP directory server as the user key.

Important:

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, the sAMAccountName attribute value of an end user in one domain might match that of another end user in another domain. In this case, 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.

When the authentication context matches specific mappings between the authentication sources, authentication policy contracts, or password credential validators, the attributes map into access tokens. The HTTP RequestJava object retrieves the authentication method that a client uses, or the private key JWT for client authentication if the client uses the private_key_jwt authentication method. The HTTP Request Java object maps it into the access tokens.

Data stores used here retrieve any required user attributes.

Runtime processing

At runtime, the first time a client requests an OAuth token, the process employs the two mapping sequences. Every time an existing persistent grant requests a new access token, the process invokes the second mapping.