English

oidc
oauth
token-exchange
openid

Understanding token exchange in OAuth/OIDC

Token exchange is an OAuth extension enabling trusted clients to obtain new tokens without user interaction, useful for impersonation, automation, cross-system integration, and token migration in various scenarios.

Sijie

Developer

9/11/20243 min read

Stop wasting weeks on user auth

Launch secure apps faster with Logto. Integrate user auth in minutes, and focus on your core product.

Get started

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:

Token issuer: issues the subject token to the client application.
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.

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.
subject_token: REQUIRED. The user's PAT.
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.
resource: OPTIONAL. The resource indicator, help to specify the target resource for the access token.
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.
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.

Comparison with authorization code flow#

Redirection#

Token issuer and token exchange service#

When to use token exchange?#

Token exchange process#

Client application#

Token exchange request#

Token exchange in Logto#

Comparison with authorization code flow#

Redirection#

Token issuer and token exchange service#

When to use token exchange?#

Token exchange process#

Client application#

Token exchange request#

Token exchange in Logto#

Comparison with authorization code flow

Redirection

Token issuer and token exchange service

When to use token exchange?

Token exchange process

Client application

Token exchange request

Token exchange in Logto

Comparison with authorization code flow

Redirection

Token issuer and token exchange service

When to use token exchange?

Token exchange process

Client application

Token exchange request

Token exchange in Logto