Token Exchange Grant

The RFC 8693 - OAuth 2.0 Token Exchange facilitates the secure exchange of tokens for accessing different resources or services. This documentation guides you through enabling this grant type on your authorization server, detailing request and response handling to ensure robust and secure token management.

Enable this grant

To enable the token exchange grant, you'll need to provide your own implementation of processTokenExchangeFn. This function should orchestrate the exchange with the required third-party services based on your specific needs.

authorizationServer.enableGrant({
  grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
  processTokenExchangeFn: async (
    args: ProcessTokenExchangeArgs,
  ): Promise<OAuthUser | undefined> => {
    const {
      resource,
      audience,
      scopes,
      requestedTokenType,
      subjectToken,
      subjectTokenType,
      actorToken,
      actorTokenType,
    } = args;

    // Implement the logic to handle the token exchange.
    // This could involve validating the subject token, interacting with third-party services,
    // and generating or retrieving an appropriate access token for the user.
    // Example:
    const user = await exchangeTokenForUser(subjectToken, subjectTokenType);

    // Return the user object associated with the exchanged token, or undefined if exchange fails
    return user;
  },
});

Flow

The client sends a POST to the /token endpoint with the following body:

grant_type must be set to urn:ietf:params:oauth:grant-type:token-exchange
client_id is the client identifier you received when you first created the application
subject_token a security token that represents the identity of the party on behalf of whom the request is being made
subject_token_type an identifier, as described in Section 3, that indicates the type of the security token in the subject_token parameter See more info
actor_token (optional) a security token that represents the identity of the acting party
actor_token_type (optional but required when actor_token is present) an identifier that indicates the type of the security token in the actor_token parameter See more info
resource (optional) a URI that indicates the target service or resource where the client intends to use the requested security token.
audience (optional) is the logical name of the target service where the client intends to use the requested security token.
requested_token_type (optional) is an identifier for the type of the requested security token See more info
scope (optional) is a string with a space delimited list of requested scopes. The requested scopes must be valid for the client.

Details

View sample request

Did you know? You can authenticate by passing the client_id and client_secret as a query string, or through basic auth.

POST /token HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_id=ec6875c5-407a-4242-947a-1ab5e6ad632f
&requested_token_type=urn:ietf:params:oauth:token-type:access_token
&subject_token={steam_session_id}
&subject_token_type=urn:ietf:oauth:token-type:steam_session_ticket
&scope="contacts.read contacts.write"

The authorization server will respond with the following response.

token_type will always be Bearer
expires_in is the time the token will live in seconds
access_token is a JWT signed token and can be used to authenticate into the resource server
scope is a space delimited list of scopes the token has access to

View sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
token_type: 'Bearer',
expires_in: 3600,
access_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDE3MDY0NjYsIm5iZiI6MTYwMTcwMjg2NiwiaWF0IjoxNjAxNzAyODY2LCJqdGkiOiJuZXcgdG9rZW4iLCJjaWQiOiJ0ZXN0IGNsaWVudCIsInNjb3BlIjoiIn0.KcXoCP6u9uhvtOoistLBskESA0tyT2I1SDe5Yn9iM4I',
scope: 'contacts.create contacts.read'
}

Flow​

Flow