PingFederate Server

Token exchange grant

You can configure the PingFederate OAuth server to support the token exchange grant type.

This feature uses the protocol defined in the OAuth 2.0 token exchange specification RFC 8693. For information about the protocol, see OAuth 2.0 Token exchange. For information about configuring the OAuth server for token exchange, see OAuth token exchange.

An OAuth token exchange begins when an OAuth client sends a token exchange request to the PingFederate OAuth server. The request contains the token exchange grant type parameter, a subject token, and a subject token type parameter. For impersonation use cases, the request also contains an actor token and actor token type parameter. The request might also contain resource, audience, scope, and requested token type parameters.

The optional resource parameter identifies an Access Token Management (ATM) instance or token generator instance. The optional audience parameter identifies another client that will use the new token to get access to a resource. If a request includes an audience parameter, the OAuth server will select the ATM instance specified in the audience client’s configuration as seen in step 2.

A successful token exchange ends when the OAuth server sends the client a message containing the requested token. The response also contains an issued token type parameter and a token type parameter.

To function as the authorization server, PingFederate requires at least one Token Exchange Processor Policy (TEPP) in order to utilize the token exchange grant type. For more information, see Defining token exchange processor policies. A TEPP includes a map of subject token types to token processor instances and a map of attributes from the request and other sources to a TEPP attribute contract. You must assign a default TEPP to the OAuth server. Optionally, you can assign a TEPP to OAuth clients that need to exchange tokens.Flowchart showing the four steps in the process of Token Exchange.

When the OAuth server receives a token exchange request from an OAuth client:

  1. The OAuth server selects a TEPP and fulfills the TEPP attribute contract as follows:

    • If the OAuth client’s configuration specifies a TEPP, the OAuth server selects that TEPP. Otherwise, the OAuth server selects the default OAuth server TEPP.

    • The OAuth server uses the TEPP’s map of subject token types to select a token processor instance. The token processor then uses the TEPP’s attribute map to produce a TEPP attribute contract.

  2. The OAuth server selects a token generator instance or ATM instance as follows:

    • If the request does not have an audience or resource parameter, the OAuth server selects the default OAuth server ATM instance.

    • If the request includes resource parameters, audience parameters, or both, and if the OAuth server determines that they identify a single ATM or token generator instance, the OAuth server selects it.

    • If the request includes resource parameters, audience parameters, or both, and if the OAuth server determines that they do not identify a single ATM or token generator instance, the OAuth server returns an error.

  3. The token generator or ATM uses the attribute contract to generate the token as follows:

    • The default token type is generated if the request does not include a requested token type parameter.

    • If the request includes a requested token type parameter, that type of token is generated.

    • If the request includes a requested token type but the token generator or ATM does not support that token type, the OAuth server returns an error.

  4. The OAuth server sends the client a response containing the requested token.