Skip to content

Exchange User Access Token

This guide explains how to exchange a user access token from another application on the behalf of the user. In many scenarios, an application (client 1) needs to access resources on the behalf of a user. Often, the user is not directly interacting with the application (client 1), but has passed to the application an access token representing the user's identity. This access token has been obtained by the user through an authentication process with another application (client 2) and thus the scting application (client) needs to exchange this token for its own access token to access the resources on the behalf of the user.

Reference: https://oauth.net/2/token-exchange/

Preliminary requirements

  • The access token must be valid and not expired. This is important because an access token has a limited lifetime and the application (client 1) must ensure that the access token is still valid before exchanging it for another access token. This is why the exchange should be done as soon as possible after the access token has been obtained.
  • The application (client 1) must be registered in the Terradue IAM service and have obtained a client ID and a client secret. This is required to authenticate the application (client 1) with the Terradue IAM service and to obtain the access token.
  • The application (client 1) must have the necessary permissions to exchange the access token. This is defined in the IAM service when the application (client 1) is registered.

Exchange the access token

The access token is exchanged by sending a POST request to the token endpoint of the Terradue IAM service. The request must contain the following parameters:

  • client_id: The client ID of the application (client 1).
  • client_secret: The client secret of the application (client 1).
  • grant_type: The value must be urn:ietf:params:oauth:grant-type:token-exchange.
  • subject_token: The access token obtained by the user from another application (client 2).

The following is an example of a POST request to exchange the access token:

POST /realms/master/protocol/openid-connect/token HTTP/1.1
Host: iam.terradue.com
Content-Type: application/x-www-form-urlencoded

An implementation of the request using the curl command is shown below:

curl -X POST "https://iam.terradue.com/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=client1" \
  -d "client_secret=client1-secret" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token={token}"

The response to the request contains the exchanged access token. The following is an example of a response:

{
   "access_token" : ".....",
   "refresh_token" : ".....",
   "expires_in" : "...."
}

Example in python is available in the Exchange Access Token notebook.

Exhanged access token lifetime

The exchanged access token has a limited lifetime and the application (client 1) must ensure that the access token is still valid before using it to access the resources. The lifetime of the exchanged access token is defined in the Terradue IAM service when the application (client 1) is registered.

Offline scope

The exchanged access token can have an offline scope. This scope allows the application (client 1) to obtain a refresh token that can be used to obtain a new access token when the access token has expired. The offline scope is defined in the Terradue IAM service when the application (client 1) is registered.