OAuth 2.0 Token Exchange

Working as an OAuth 2.0/OpenID Connect authorization server, and following 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 OAuth2 Provider service is configured to issue refresh tokens, it will also issue them after a token exchange when appropriate. However, AM does not allow the exchange of tokens for refresh tokens as part of the token exchange flows. Exchanging tokens for SAML assertions is also not supported.

Note

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

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

OAuth 2.0 Token Exchange or the Security Token Service (STS)?

Even though the goal of both implementations is transforming tokens, they are completely different in implementation and capabilities:

The STS service lets AM establish cross-domain trust federation relationships. To do this, AM provides a REST STS framework loosely based on the SOAP WS-Trust specification that you need to build, deploy, and maintain yourself.

The REST STS service supports username/password, SSO tokens, X.509 certificates, and ID tokens as input tokens, and SAML v2.0 assertions and ID tokens as output tokens.

Due to its transformation capabilities, the STS service is more suitable to helping federate legacy platforms.

The OAuth 2.0 Token Exchange specification makes use of AM as an OAuth 2.0/OpenID Connect authorization server to transform OAuth 2.0-related tokens.

Use the OAuth 2.0 Token Exchange in OAuth 2.0/OpenID Connect platforms.

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 of the OAuth 2.0/OpenID Connect flows that AM supports.

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

The new token resulting from token exchange is referred as exchanged token in this documentation.

The cornerstone of token exchange is the may_act claim. The claim, as explained in RFC 8693, 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.

For more information and implementation details, see About the may_act Claim.

Token exchange operations are logged under the AM-TOKEN-EXCHANGE audit event, and new tokens can be tracked using the value of their auditTrackingId claim.

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

It copies, from the subject token, the claims and values that must stay the same in the new 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. In the same way, claims in the new token that cannot be inferred from the subject token because they are of a different type, are not added.
Scopes are not copied from the subject token. AM derives them from the regular scope implementation that is used in the OAuth 2.0/OpenID Connect flows (see About Scopes).
It 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 OAuth2 Provider service, has passed.

Restricted and Expanded Tokens

Exchanged tokens do not need to have the exact same scopes/claims that the subject token does. Tokens can have their scopes/claims restricted or expanded:

Exchanged tokens are restricted when their scopes/claims are a subsection of those available to the subject token. The idea behind this is that, rather than gathering consent for different sets of scopes/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/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 interaction with the user during token exchange. Therefore, it is impossible for AM to request consent about the expanded scopes/claims. It is the responsibility of the client application to ensure that either the user has consented beforehand, or that the expanded scope/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 another person when performing a job or duty. OAuth 2.0/OpenID Connect impersonation is a token exchange use case whereby a client performs an action on behalf of the user on an environment where there is no need to keep a separation between the user and the client.

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

As a high-level explanation, the client in possession of an access or ID token on behalf of the user (the subject token) obtains a new access token or ID token that is identical to the original in terms of its privileges (unless the exchanged token's scopes/claims have been expanded or restricted).

Impersonated tokens cannot be told apart from regular tokens, since they do not have any specific claim or value that indicates they are the result of an impersonation flow. This is different for delegated tokens, as you will see later in this section.

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

Impersonation Example Use Cases

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 reach out to the internal banking systems to perform the transaction.

When the user logs in, they receive the subject token, which is an access token with the 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:

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:

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 giving a job or duty to someone else to perform it on your behalf. OAuth 2.0/OpenID Connect delegation is a use case of token exchange whereby a client performs an action on behalf of the user on an environment where keeping the user and client as different entities is important.

As a high-level explanation, 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). Then, 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).

However, 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 could be adapted, therefore, to perform different actions when presented with a delegated token.

About the act Claim

The act claim, as explained in RFC 8693, is a JSON object that expresses that delegation has occurred. It also identifies the party that acts on behalf of the subject of the token. For example:

"act": {
  "sub": "(usr!demo)"
}

The sub object of the act claim is always the subject of the actor token used during delegation.

This approach is more secure if the token must travel through third-party systems, because even if the token was 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 is phoning a call center because of a problem with their water supply. The operator that picks up the phone verifies the identity of the user 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 so that when they book a repair for the user, both the operator and the user are reflected on the repair request:

The delegated token is a restricted token, since 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:

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 OAuth2 Provider service and the relevant client profiles for token exchange.	"Configuring AM for Token Exchange"
Learn how to exchange tokens for impersonation and delegation.	"Token Exchange Flows"