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

  • urn:ietf:params:oauth:token-type:id-jag

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 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, an service provider (SP) connection, or a token generator instance. For most use cases, use an ATM instance or SP connection. Use token generator instances for advanced scenarios. The optional audience parameter identifies either another client or an SP connection entity ID, depending on the value of the requested_token_type parameter. If a request includes an audience parameter, the AS selects either the ATM instance specified in the audience client’s configuration or the SP connection identified by the audience value, depending on the value of the requested_token_type parameter.

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 and the subject_token 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, SP connection, or token generator instance. For most use cases, use an ATM instance or SP connection. 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 instance, SP connection, or token generator instance, PingFederate selects it. Otherwise, PingFederate returns an error.

  3. The selected ATM instance, SP connection, 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 an actor_token and actor_token_type parameter.