OAuth 2.0 Token Exchange Flow

OAuth 2.0 Token Exchange is an extension of the OAuth 2.0 framework, designed to allow a client application to exchange one type of OAuth token for another. This mechanism provides a way for trusted services or clients to obtain or swap tokens in a secure manner. Token exchange is particularly useful when a service or application needs to acquire a different type of token to access a resource or perform a specific action.

Let’s look at how this token exchange flow differentiates from the traditional OAuth flows designed to obtain an access token.

Traditional OAuth is primarily designed for the delegation of access permissions, allowing the client application to access resources on behalf of a user by obtaining an access token. It’s commonly used for user authentication and authorization in various scenarios, including social media login, single sign-on, and third-party application access. OAuth Token Exchange is specifically designed to exchange one type of token for another, typically for trusted clients to acquire a different kind of token without requiring user involvement. It’s used for various scenarios where a client application needs a specific token to access a resource, such as swapping an access token for a security token or an identity token.

Traditional OAuth involves flows such as Authorization Code Flow, Implicit Flow, and Client Credentials Flow. These flows are designed for different use cases, including web applications, single-page applications, and confidential clients. OAuth Token Exchange introduces its own token exchange flow, which allows a client application to request a token of a different type. The token exchange flow is specifically designed for token transformation and exchange.

In traditional OAuth, there is user involvement. The user typically grants permission to the client application to access their data on a resource server. This involves user authentication and consent. In OAuth Token Exchange, user involvement is minimized or absent. The exchange is typically performed by trusted clients or services that have the necessary authorization, and it’s often done without requiring the user to re-authenticate or provide consent.

Let’s look at some of the core concepts related to the token exchange to get a better idea about the possible use cases. The below diagram shows the scenario where the initial token is obtained using the OAuth 2.0 authorization code grant and that token is then exchanged.

Client Application

The client application, which is seeking to exchange tokens, initiates the token exchange process. This client application typically already holds an access token but needs a different kind of token that is issued by a different issuer to access a specific resource. A client application must be registered with the OAuth 2.0 authorization server. During the registration process, the client application is issued a unique client identifier (client ID) and a client secret to authenticate itself with the authorization server.

Prior to initiating the token exchange flow, the client application may use various OAuth 2.0 grant types to authenticate with the authorization server and obtain an access token initially. This typically involves user authentication if the client is acting on behalf of a user.

Token Exchange Request

The client sends a token exchange request to the token exchange service, often using a designated OAuth 2.0 endpoint. This request includes the current token, the target token type it needs, and any additional parameters required by the service.

Here are the key parameters that should be present in a token exchange request

• Grant Type

The grant_type parameter specifies the type of token exchange being requested. In the context of Token Exchange, this is usually set to "urn:ietf:params:oauth:grant-type:token-exchange". This indicates the intent to exchange tokens.

• Subject Token

The subject_token parameter contains the token that the client application currently holds and wishes to exchange. This token can be an OAuth access token or another type of token.

• Subject Token Type

The subject_token_type parameter specifies the type or format of the subject token. Common values include "urn:ietf:params:oauth:token-type:access_token" for OAuth access tokens, but it can vary based on the token being exchanged.

Apart from these, there are a few additional optional parameters

• Audience

The audienceparameter specifies the intended audience for the exchanged token. The audience can indicate the resource or service for which the exchanged token will be used.

• Resource

The resource parameter is used to specify the target resource server or service where the exchanged token will be presented. It can help ensure that the exchanged token is valid for that resource.

• Scope

If scopes are applicable to the token exchange, the scope parameter can be used to define the desired permissions associated with the exchanged token. The scope value may restrict the actions the token can perform.

Here is a sample token exchange request. As mentioned earlier, the client application may be required to obtain authorization prior to sending the token exchange request and include an authorization header in the token exchange request.

POST /oauth2/token HTTP/1.1
Host: https://localhost:9443
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64-encoded-clientId:clientSecret>

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&audience=http://localhost:8080
&resource=resource-server.com/api/resource
&scope=read write

Token Issuer

This is the authorization server that issues the initial token. Client application initially retrieves this token and send this to the token exchange service in order to obtain a new token.

Token Exchange Service

The token exchange service validates the request, ensuring that the client is authorized to make the exchange. It may also perform additional checks, such as verifying the original access token’s scope or expiration time.

Once the request is validated, the token exchange service issues the new token and sends it back to the client. The client can now use the newly acquired token to access the resource or perform the desired action. This token is suitable for the specific resource, and the client doesn’t need to undergo a full authentication and authorization process again.

So as you can see token exchange is particularly valuable in scenarios where a client application requires different types of tokens for interacting with various services or resources within a secure environment. For example, it’s used in cases where an OAuth access token needs to be exchanged for a security token or an identity token to access a specific API or gain additional permissions without requiring the user to re-authenticate.