How does ForgeRock AM Token Exchange (RFC 8693) work?

Token Exchange (RFC 8693) is an OAuth 2.0 extension grant type that allows a client to exchange one security token for a different one with different properties — different subject, different scopes, different lifetime, or a different format. ForgeRock AM 7.x supports the Token Exchange grant natively, enabling delegation and impersonation patterns that are common in microservices architectures.

The Token Exchange grant type uses urn:ietf:params:oauth:grant-type:token-exchange as the grant type value. Key parameters:

• subject_token — The token being exchanged (access token, ID token, or SAML assertion).
• subject_token_type — The type of the subject token (e.g., urn:ietf:params:oauth:token-type:access_token).
• requested_token_type — The type of token desired in return.
• actor_token — (Optional) The identity of the intermediate service requesting the exchange on behalf of a subject — used for delegation scenarios.

Two key patterns enabled by Token Exchange:

Delegation — Service A calls Service B on behalf of User X. Service A has its own token but needs a token that represents "Service A acting on behalf of User X". Service A exchanges its token plus a subject token (User X's token) and receives a composite token with both identities. The resulting token's act claim contains the actor (Service A's client ID) and the sub is User X.

Impersonation — A trusted back-office service needs to act as another user for administrative purposes. It exchanges its own high-privilege token for a token representing the target user's identity. This requires explicit trust configuration in AM — the requesting client must be granted impersonation rights to prevent abuse.