Token Exchange service overview

Token Exchange is a service that is specified in RFC 8693.

The Token Exchange service is able to receive and validate security tokens and issue new security tokens in response. This exchange of security tokens serves many purposes:

  • The client may obtain a security token that is valid in another security domain (i.e., different signing keys).
  • The security token may contain different claims (i.e., the sub claim may use the value of a different claim, different audience or scopes).
  • Token Exchange may be used in delegation and impersonation use cases.

Use case scenarios

The following figure shows a typical use case scenario, where a separate Token Exchange server (Standalone OAuth AS) is deployed to serve a number of different security domains.

In this scenario, we find a number of security zones (frontend zones in blue) that are exposed over the Internet to service clients used by end-users. These zones could be different sales organizations or different geographical websites.

The services in the different frontend security zones connect to a number of central services zones (backend in red and green). These zones could be a centralized billing or a centralized order management component.

The figure includes the following elements:

Security zones

The use case shows different security zones in different colors.

Blue: Several security zones that allow end-user clients to obtain security tokens from a shared authorization server (FE OAuth AS).

Red/green: Two security zones that require security tokens that are only valid in their respective zones.

Security tokens

Blue: Security tokens that are valid only within the blue security zones. The blue tokens are issued to clients in the User zone.

Red/green: Tokens that are valid only in their respective zones. The tokens are issued by the Token Exchange Server (Standalone OAuth AS).

Token Exchange server

The Token Exchange server (Standalone OAuth AS) will receive requests from servers in the blue zone with blue tokens as subject token.

The Token Exchange server will issue either red or green tokens depending on the audience or resource information in the request.

PEP (Policy Enforcement Point)

The policy enforcement points (PEP) in these zones validate the tokens using the key material from either the FE OAuth AS (blue zone) or the Token Exchange Server (red and green zones).

Each PEP will only validate the tokens of its own security zone.

Client

The authorization server of the blue zone will only accept end-user clients requesting security tokens. Typical token requests in this zone will use the Authorization Code Flow.

The Token Exchange server (Standalone OAuth AS) will only accept servers from the blue zones as clients. On such servers will be able to obtain exchanged tokens.

Alternative use case scenarios:

Integrated deployment

In an integrated use case scenario, the Token Exchange server is deployed directly on the authorization server.

This scenario is used to minimize the number of installations of Airlock IAM. On the downside, the security segregation between clients connecting to the authorization server and clients connecting to the Token Exchange server is no longer possible.

Segregated deployment

In a segregated use case scenario, every security domain hosts its own Token Exchange server.

This scenario is the most secure since each Token Exchange server tightly controls which clients are allowed to connect and manages its own keys to issue tokens. The price for the security gain is both deployment costs (additional Token Exchange servers) and increased configuration complexity.

Note that in this scenario the frontend servers must be able to request tokens from different Token Exchange servers based on the audience or resource configuration.

Token exchange properties

Actor token

The actor token is a second token for impersonation and delegation use cases.

The actor token and the validation of the actor token are optional.

actor_token_type

requested_token_type

subject_token_type

When sending a request to the token exchange, the client must declare the types of the tokens supplied.

IAM is able to process the following token types:

  • actor_token_type: jwt
  • requested_token_type: access_token, jwt
  • subject_token_type: access_token, jwt

For an example, see Token Exchange Use Case example

Actor Token Validation and

Subject Token Validation

For each token, the configurator must decide whether the token is to be validated (including signature verification) or claims should only be extracted (ignoring signatures).

In case of validation, the Token Exchange server will validate the token locally and retrieve the key material through OIDC discovery from the AS that issued the token.

If the retrieval of the key material or the signature validation fails, the token exchange will immediately fail.

In case of claims extraction, the token is only parsed without signature validation.

Client

In the context of a token exchange, the system that sends a request to the Token Exchange endpoint is considered the client.

This system may differ from the client that obtained the original token.

Client authentication

Token Exchange is implemented as an additional grant of the standard authorization server and therefore supports all the client authentication methods available.

Subject token

In the request, the client presents the subject token to the Token Exchange server as a parameter.

The subject token is mandatory, but the validation is optional.

Token introspection endpoint

The Token Exchange server does not provide a token introspection endpoint.

Token revocation

The Token Exchange server does not support token revocation.

User interaction

Token exchange is a non-interactive exchange of security tokens. It is not possible to interact with the user.

Delegation and impersonation

The standard RFC 8693 defines delegation and impersonation as follows:

Impersonation

A principal P impersonates principal B, which means P is given all of B's rights within a defined context. P is indistinguishable from B in this context.

Delegation

A principal P is a delegate of principal B, which means P still has its own identity separate from B, and it is explicitly understood that while B may have delegated some of its rights to P, any actions taken are being taken by P, representing B.

Within the context of the Token Exchange service, IAM supports impersonation and delegation as follows:

  • In the request, the mandatory subject_token must be supplied.
  • The Token Exchange server can either validate the entire subject_token or only extract the claims from the token without signature validation.
  • In the request, an optional parameter actor_token may be supplied.
  • The Token Exchange server can either validate the entire actor_token or only extract the claims from the token without signature validation. The actor information can then be added to the resulting token in the act claim.
  • If an act claim is added to the exchanged token, this is considered a delegation. If the act claim is missing from the exchanged token, this is considered an impersonation.

An example use case would be a help desk employee who needs to represent a customer during a phone call. The help desk employee needs to exchange the current access token with a token that allows him to represent the customer as a delegation.

Request parameters

  • subject_token: JSON structure that contains the customer's information. A claim extractor plugin is recommended to process this token.
  • actor_token: Access token of the help desk employee. A validator plugin is recommended to process this token.

In the REST response, a new access token is issued to the client of the help desk employee with the following contents:

Exchanged token content

  • sub = customer
  • act = help desk employee

Recommendations:

For security reasons, it is recommended that at least one token is validated. It depends on the use case scenario which token should be validated.

In a delegation use case, both subject and actor information should be logged.

Known limitations

This implementation of the Token Exchange service has the following known limitations. The Token Exchange server:

  • Only accepts JWT tokens.
  • Only issues access tokens (JWT).
  • Only works with subject tokens issued by an OpenID provider if token validation is required.
  • Does not use token introspection to validate the subject token. As a consequence it is possible to exchange revoked subject tokens.
  • Does not support certificate binding.
  • Does not support opaque tokens.