Understanding token exchange in OAuth/OIDC

Introduced in RFC 8693, token exchange is an OAuth extension that allows trusted clients to exchange an existing token for a new one with different attributes or scopes. This mechanism is particularly useful for a service, an application or an end user to obtain a normal OAuth access token via a pre-authorized token, without the need to go through the full OAuth flow.

Comparison with authorization code flow#

First, let's take a look at the OAuth Authorization Code flow, which is the most common flow for obtaining an access token.

And this is the token exchange flow:

Redirection#

The main difference is that in the authorization code flow, the client application redirects the user to the authorization server to obtain an access token. In the token exchange, the client application can exchange a token with the authorization server without involving the user to redirect.

That is because in the authorization code flow, the client application is not "trusted" and needs to know the user's credentials to obtain an access token. In the token exchange, the client application is trusted to have obtained the token from the user already, and the authorization server will validate the token and issue a new one.

Token issuer and token exchange service#

In the token exchange flow, the "Auth Server" is now two participants:

1. Token issuer: issues the subject token to the client application.
2. Token exchange service: validates the subject token and issues a new token to the client application.

The token exchange service is the same as "Auth Server" in the authorization code flow, and the token issuer can be a third-party identity provider, or splited from the "Auth Server" as a dedicated service.

When to use token exchange?#

Token exchange flow can be performed without user interaction, this is useful in the following scenarios:

• Impersonation: Allow services (e.g., backend microservices) or admin users to perform actions on behalf of a user without exposing full user credentials.
• Automation: Allow trusted services to perform actions automatically without manual intervention, or perform automated testing.
• Integration with Other IdPs: Translate tokens across different identity systems to maintain a seamless user experience and manage permissions effectively, one common scenario is to translate a SSO token to a token for a downstream service.
• Migration: Migrate tokens from one authorization server to another, for example, from a legacy system to a modern OAuth/OIDC-compliant system.

Token exchange process#

Exchanging for a new access token is the most common use case, we'll take this as an example. Not limited to access token, token exchange can also be used to issue other types of tokens such as refresh token, ID token, etc.

Client application#

To perform token exchange, a registered client application with the authorization server is required.

And the client application must have a subject_token prior to initiating the token exchange flow, this token is usually granted by the authorization server or the trusted third-party identity provider. By having this token, the client application can now be "trusted" to exchange tokens without the need of user's credentials and interaction.

Token exchange request#

The client sends a request to the authorization server's token endpoint to exchange an existing token. This includes the subject_token (the token being exchanged) and optionally, the desired target audience, scope, and token type.

1. grant_type: REQUIRED. The value of this parameter must be urn:ietf:params:oauth:grant-type:token-exchange indicates that a token exchange is being performed.
2. subject_token: REQUIRED. The user's PAT.
3. subject_token_type: REQUIRED. The type of the security token provided in the subject_token parameter. A common value of this parameter is urn:ietf:params:oauth:token-type:access_token, but it can vary based on the token being exchanged.
4. resource: OPTIONAL. The resource indicator, help to specify the target resource for the access token.
5. audience: OPTIONAL. The audience of the access token, indicating the intended recipients of the token, the authorization server may use the value of resource if audience is not specified.
6. scope: OPTIONAL. The requested scopes.

Also, the request needs to include the client information, which can be encoded as a Basic Auth header or sent as form data.

Here is an example request:

Token exchange in Logto#

Logto supports token exchange out of the box, including impersonation and personal access tokens.