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. Learn more about OAuth 2.0 token exchange in RFC 8693. Learn more about configuring the OAuth server for token exchange in OAuth token exchange.

PingFederate supports the following token types:

  • urn:ietf:params:oauth:token-type:access_token

  • urn:ietf:params:oauth:token-type:saml1

  • urn:ietf:params:oauth:token-type:saml2

  • urn:params:oauth:token-type:jwt

A token exchange begins when a OAuth client sends a token exchange request to the PingFederate OAuth authorization server (OAuth AS). The request contains the token exchange grant type parameter, a subject_token, and a subject_token_type parameter. For impersonation use cases, the request can also include actor_token and actor_token_type parameters. 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 a token generator instance. For most use cases, use an ATM instance. Use token generator instances for advanced scenarios. 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 AS selects the ATM instance specified in the audience client’s configuration as described in the internal processing steps.

A successful token exchange ends when the AS sends the client a response containing the requested token. The response also contains issued_token_type and token_type parameters.

To function as the AS, PingFederate requires at least one Token Exchange Processor Policy (TEPP) to use the token exchange grant type. Learn more in Defining token exchange processor policies. A TEPP includes a map of subject token types, and optionally actor 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.

Example use case

In this scenario, a user or mobile application calls an API gateway using an existing external access token. The API gateway must then call an internal microservice to complete the request, but the internal microservice requires a different token. The API gateway acts as the OAuth client for the token exchange and sends a token exchange request to the PingFederate AS. PingFederate returns a new token that the API gateway uses to call the internal microservice.

Sequence diagram showing a token exchange flow between a user or mobile app, an API gateway acting as an OAuth client, PingFederate AS, and an internal microservice resource server.
Token exchange flow

The following steps outline the end-to-end flow:

  1. A user or mobile application calls the API gateway using an existing external access token.

  2. The API gateway determines that it must call an internal microservice and that the microservice requires a different token.

  3. The API gateway sends a token exchange request to the PingFederate AS containing the token exchange grant type, subject_token, and subject_token_type parameters.

  4. PingFederate processes the request and returns a new token to the API gateway.

  5. The API gateway uses the new token to call the internal microservice.

  6. The internal microservice validates the token and returns the data.

  7. The API gateway returns the resource to the user or mobile application.

Internal PingFederate processing

When PingFederate receives a token exchange request from an OAuth client, it performs the following processing:

  1. PingFederate selects the TEPP. If the OAuth client’s configuration specifies a TEPP, PingFederate selects that TEPP. Otherwise, PingFederate selects the default OAuth server TEPP. PingFederate then uses the TEPP’s map of subject token types, and optionally actor token types, to select a token processor instance, which uses the TEPP’s attribute map to produce a TEPP attribute contract.

  2. PingFederate selects an ATM instance or token generator instance. For most use cases, use an ATM instance. Use token generator instances for advanced scenarios. If the request does not include an audience or resource parameter, PingFederate selects the default OAuth server ATM instance. If the request includes resource parameters, audience parameters, or both, and they identify a single ATM or token generator instance, PingFederate selects it. Otherwise, PingFederate returns an error.

  3. The selected ATM or token generator instance uses the attribute contract to generate the token. If the request does not include requested_token_type, the default token type is generated. If the request includes requested_token_type, that type is generated. If the requested token type is not supported, PingFederate returns an error.

  4. PingFederate sends the client a response containing the requested token.

For impersonation use cases, the request can also include actor_token and actor_token_type parameters.