Identity Cloud

Token exchange

Working as an OAuth 2.0/OpenID Connect authorization server, and following the OAuth 2.0 Token Exchange specification, AM can exchange:

  • Access tokens for access tokens

  • Access tokens for ID tokens

  • ID tokens for ID tokens

  • ID tokens for access tokens

If the OAuth 2.0 provider service is configured to issue refresh tokens, it will also issue them after a token exchange, when appropriate. However, you cannot exchange tokens for refresh tokens as part of the token exchange flow. You can also not exchange tokens for SAML assertions.

Clients can only exchange tokens at the OAuth 2.0 provider that issued them. For example, if a token was issued by https://<tenant-env-fqdn>/am/oauth2/, it cannot be exchanged at https://my.example.com:8443/am/oauth2/.

The same restriction applies across realms, although this is in line with other AM features, to ensure that realms are separate entities.

How does token exchange work?

Exchanging tokens requires, at least, a subject token, which is the original token to be exchanged. The subject token can be obtained using any supported OAuth 2.0/OpenID Connect flow.

An actor token can also be included in certain token exchange requests. The actor token represents an identity that acts on behalf of another identity.

We refer to the new token, resulting from the token exchange, as the exchanged token.

The cornerstone of token exchange is the may_act claim (see RFC 8693). This claim is a JSON object that specifies the party or parties allowed to act on behalf of the subject of the token. Only the client or the client/subject combination specified in the may_act claim can exchange that token for another token. For more information and implementation details, see About the may_act claim.

AM performs token exchange as if it were issuing a normal token of that type. The only differences are:

  • AM copies the claims and values that must stay the same (in the new token) from the subject token; for example, claims related to the subject or to the issuer of the token.

    Claims that are not relevant, because the new token is of a different type, are not copied over. Claims in the new token that cannot be inferred from the subject token (because they are of a different type) are also not added.

    Scopes are not copied from the subject token. AM derives the scopes from the regular scope implementation that is used in the OAuth 2.0/OpenID Connect flows (see OAuth 2.0 scopes).

  • AM adds the may_act and the act claims, when relevant.

For examples of new exchanged tokens, see Token exchange flows.

Exchanged tokens do not expire at the same time as the subject tokens used to create them. Rather, they expire after the amount of time specified in the Access Token Lifetime (seconds) or the OpenID Connect JWT Token Lifetime (seconds) fields of the OAuth 2.0 provider service has passed.

Restricted and expanded tokens

An exchanged token does not need identical scopes and claims to the subject token. An exchanged token can have its scopes and claims restricted or expanded:

  • Exchanged tokens are restricted when their scopes and claims are a subsection of those available to the subject token. Instead of gathering consent for different sets of scopes and claims, clients gather consent for a broad range initially, and then exchange the broad-scoped token for as many restricted tokens as required.

  • Exchanged tokens are expanded when they are granted scopes and claims that are not included in the subject token. Expanding tokens works best when exchanging between ID and access tokens, due to the differences between scopes and claims.

There is no user interaction during token exchange. Therefore, it is impossible for AM to request consent for expanded scopes or claims. The client application must ensure that the user has consented beforehand, or that the expanded scope or claim is unrelated to the user’s resources.

For examples of restricted and expanded tokens, see Token exchange use cases.

Token exchange use cases

Clients may want to exchange tokens for impersonation and delegation purposes:

Impersonation

To impersonate means to pretend you are someone else when performing a job or duty. OAuth 2.0/OpenID Connect impersonation is a token exchange use case where a client performs an action on behalf of the user in an environment where there is no need to keep a separation between the user and the client.

For example, a user uploads a picture to social media using an app. It is not important for the downstream social media servers to differentiate the user from the client, to resize and store the picture.

The client possesses an access or ID token on behalf of the user (the subject token) and obtains a new access or ID token that is identical to the original in terms of its privileges (unless the exchanged token’s scopes or claims have been expanded or restricted).

Impersonated tokens cannot be distinguished from regular tokens, because they have no specific claim or value that indicates they are the result of an impersonation flow. This is different for delegated tokens.

Due to the risk of identity theft, allow token impersonation across trusted systems only.

Impersonation example use case

Consider a user who wants to do a money transfer using their bank application. The user logs in to the application, and trusts the application to act on their behalf, to access the internal banking system to perform the transaction.

When the user logs in, they receive the subject token, which is an access token with read_accounts, create_accounts,transfer, and change_data scopes. These scopes represent every banking service they can use in the app.

If the user only wants to make a money transfer, there is no need for the app to send all scopes to the transaction service. To reduce the security risks of impersonation, the app transforms the broad-scope access token into another access token that is restricted to the transfer scope:

oauth2-token-exchange-1

Now, consider what happens if the example used ID tokens instead of access tokens. After logging in, the user receives the subject token, which is an ID token as a proof of their login and identity. When the user wants to make a transaction, the client exchanges the user’s ID token with an access token with the transfer scope, and sends it to the transfer service:

oauth2-token-exchange-2

In this case, the impersonation token is an expanded token since it has the transfer scope, which the ID token did not have.

Delegation

To delegate means to give a job or duty to someone else, to perform the job on your behalf. OAuth 2.0/OpenID Connect delegation is a token exchange use case where a client performs an action on behalf of the user, in an environment where keeping the user and client as separate entities is important.

The client is in possession of two tokens: one on behalf of the user (the subject token), and another for itself or someone else (the actor token). Using both tokens, the client obtains a new token that is identical to the original in terms of its privileges (unless the exchanged token’s scopes/claims have been expanded or restricted).

Delegated tokens contain the act claim, which lets the resource server know that the client using the token is not the user. The implementation of the resource server can be adapted to perform different actions when presented with a delegated token.

About the act claim

The act claim, as explained in RFC 8693, indicates that delegation has occurred, and identifies the party that acts on behalf of the subject of the token.

For example:

"act": {
  "sub": "bjensen"
}

The sub field of the act claim indicates the subject of the actor token used during delegation.

This approach is more secure if the token must travel through third-party systems. Even if the token is stolen, the implementation of the resource server should not give it full privileges over the user’s resources.

Delegation example use cases

Consider a user who phones a call center because of a problem with their water supply. The operator that picks up the phone verifies the user’s identity and creates an ID token (the subject token) on behalf of the user. The operator also creates an access token (the actor token) for themselves.

Then, the operator exchanges both tokens for a delegated access token. When they book a repair for the user, both the operator and the user are reflected in the repair request:

oauth2-token-exchange-3

The delegated token is a restricted token. It can only be used for booking a repair on behalf of the user, but not for ending the user’s contract, for example.

Consider now a scenario where both the subject and the actor tokens are ID tokens. To authorize a repair, the operator could request a delegated access token with the scope of repair:

oauth2-token-exchange-4

In this case, the delegated token is an expanded token since it has the repair scope, which neither of the ID tokens had.

Review the tasks in the following table to configure token exchange in your environment:

Task Resources

Configure the OAuth 2.0 provider service and the relevant client profiles for token exchange.

Learn how to exchange tokens for impersonation and delegation.

Copyright © 2010-2022 ForgeRock, all rights reserved.