Token Exchange in OAuth: Why and How to Implement It

Sometimes, you need a token exchange when an existing token is invalid or insufficient to access a resource or service. Instead of requiring users to log in again, OAuth 2.0 Token Exchange (RFC 8693) allows a system to exchange one token for another with different attributes. This enables delegation of access, where a system can request a new token with modified scopes, audiences, or security levels. Examples of tokens that can be exchanged include access tokens, refresh tokens, ID tokens, and SAML assertions.

The token exchange flow enhances security by ensuring tokens are scoped appropriately, reducing risks from over-permissioned tokens. It also improves interoperability by bridging trust between domains and identity providers and simplifies authentication, as users don’t have to log in multiple times to access various services. Lastly, it allows short-lived access for specific use cases without exposing long-term credentials.

Token Exchange Scenarios

Impersonation and Delegation

Token exchange enables delegation and impersonation, allowing a user or client to act on behalf of another. There is a subtle difference in the semantics of impersonation and delegation. In the first case, when A is impersonating B, A becomes indistinguishable from B in the context of the issued token. This means that any entity receiving such a token actually deals with B despite A being the actor. With delegation, A keeps its identity separate from B. A represents B but acts on its own.

The token exchange protocol allows services to request a new access token based on an existing grant, i.e., access token, without having to involve the user. In addition, the specification defines a claim to maintain a trail and mark that an access token is the result of a delegation.

Cross-domain Security

Token exchange facilitates cross-domain security by allowing a token from one trusted domain to be exchanged for a token in another domain. This method is described in the OAuth Identity and Authorization Chaining Across Domains draft. The client can then use this grant to obtain a new access token from the authorization server of the target domain. For example, a user from Company A (Domain A) needs to access an API hosted by Company B (Domain B). Since each company has its identity provider and authorization server, the user’s original access token is invalid in the target domain. A token exchange is required to obtain a valid token for Company B’s API.

Token Exchange Flow in cross-domain security:

1. The user logs in via Company A’s identity provider and gets an access_token_A.

2. The client sends access_token_A to Company A’s authorization server for exchange.

3. Company A’s authorization server validates the token, processes the request, and returns a new token to the client, a JWT authorization grant that is valid at Company B’s authorization server.

4. The client uses the authorization grant to request a new token from Company B’s authorization server.

5. The authorization server from Company B validates the grant and returns a new access token (access_token_B) that is valid in Company B’s domain.

6. The client calls the API in Company B, using access_token_B, which still represents the user from step 1.

Microservice Architecture

In a microservice architecture, token exchange allows you to request a new access token with a different scope or audience based on an existing access token. This process helps enforce the principle of least privilege when making internal API calls. Token exchange is particularly useful when a request requires internal service-to-service communication with upstream APIs. By adapting access tokens to the specific capabilities and security needs of each API, token exchange ensures that minimal access rights are granted at every step. For more details, see Token Sharing Approaches.

How Does OAuth Token Exchange Work?

Token exchange is a protocol where an existing token acts as the authorization grant for requesting a new token. This existing token, known as the subject token, serves as the foundation for the exchange. The token exchange protocol is not restricted to OAuth 2.0 and OpenID Connect tokens — such as access tokens, refresh tokens, and ID tokens — the specification refers more broadly to security tokens.

While the specification does not require client authentication during a token exchange request, it is strongly recommended. Failing to enforce client authentication can introduce significant security risks, potentially allowing unauthorized token exchanges.

The token exchange protocol categorizes security tokens into three distinct types:

• Subject token
• Actor token
• Requested token

The subject token identifies the entity on whose behalf the client is requesting a new token. In most cases, the subject remains unchanged, meaning the newly issued token represents the same subject as the original subject token. For example, when backend services use token exchange to reduce the scope of existing access tokens, any new access tokens still represent the same users.

The actor, an optional token, represents the entity attempting to act on behalf of the subject. While the newly issued token continues to reflect the same subject as the original subject token, it may also include a claim that identifies the actor, providing additional context about who is making the request.

The requested token is the token returned by the authorization server in response to a token exchange request. The authorization server issues the new token based on its policies, typically considering factors like the requested scopes, token types, resources, and audiences.

Key Parameters in Token Exchange Requests:

The OAuth 2.0 Token Exchange (RFC 8693) introduces the “urn:ietf:params:oauth:grant-type:token-exchange” grant type, allowing clients to request a new token based on an existing one.

subject_token: Refers to the security token to be exchanged. This is a mandatory parameter that represents the party that the client makes the request for, for example, a user. The subject usually remains the same in the newly issued token.

subject_token_type: Refers to the URI that identifies the type of the subject token (e.g., access token, ID token). This is also a mandatory parameter.

actor_token: Usually an access or ID token representing the party that wants to act on behalf of the subject.

actor_token_type: This parameter is required if the actor_token parameter is included in the request. It describes the type of the actor token, e.g., whether it is an access or ID token.

requested_token_type: The desired type of the new token. If unspecified, the authorization server issues a type defined by its policy.

audience: The intended recipient of the new token.

scope: The permissions requested for the new token.

Example of a Token Exchange Request:

POST /token HTTP/1.1

Host: authorization-server.com

Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange

&subject_token=eyJhbGciOiJIUzI1NiIsInR… (existing token)

&subject_token_type=urn:ietf:params:oauth:token-type:access_token

&requested_token_type=urn:ietf:params:oauth:token-type:refresh_token

&audience=https://api.target-service.com

&scope=read write

Key Parameters in Token Exchange Response:

Access_token: Refers to the resulting security token. It can be any security token. This is a mandatory parameter.

Issued_token_type: Identifies the type of the issued security token. It can be an access token, ID token, or a JWT authorization grant. This is a mandatory parameter.

Token_type: If the newly issued security token is an access token, this value describes how the access token can be used. Most commonly, the bearer token is used. This is a mandatory response parameter but is only applicable if an access token is issued.

Expires_in: Specifies the durability of the security token, recommended.

Example of a Token Exchange Response:

{

“access_token”: “new-access-token”,

“token_type”: “Bearer”,

“expires_in”: 3600,

“issued_token_type”: “urn:ietf:params:oauth:token-type:access_token”

}

Best Practices for Implementing Token Exchange

When implementing token exchange, the authorization server must have robust policies that prevent privilege escalations. It is recommended to use the scopes parameter to restrict the context in which a resulting access token is valid. An exchanged token should only have the permissions needed for its specific use. The audience parameter provides an additional way to constrain the valid context of an access token. In general, follow JWT best practices and set a short expiry time to limit security risks. Lastly, you should implement logging and auditing to track token exchanges for security compliance.