Token Exchange Configuration

Prerequisites

To configure a Token Exchange server (TX), the following prerequisites must be met:

Prerequisites for the supplier of the subject tokens

  • The access or ID token supplied must be a JWT token.

Prerequisites for the TX server

  • Airlock IAM must already be configured as an OpenID provider or an authorization server.

Recommendations for the TX server

  • We recommend that the issuer of either the subject token or the actor token is an OpenID provider that exposes the standard discovery endpoint. The TX uses this endpoint to obtain the key material to verify the token. This adds an important layer of security that authenticates the correct use of the TX service.

Configuration

Configuring the OAuth 2.0 Token Exchange plugin

  1. Go to:
    Loginapp >> OpenID Connect, OAuth, SAML, One-Shot >> OAuth 2.0/OIDC Authorization Servers >> respective Authorization Server >> OAuth 2.0 Grants/OIDC Flows
  2. Create an OAuth 2.0 Token Exchange Grant plugin.
  3. The Token Exchange server plugin is ready for configuration.

Token Exchange server plugin - Subject Token Validation field

  1. In Subject Token Validation create an OpenID Connect Discovery Subject Token Validation plugin.
  2. Configure the plugin with a list of Allowed Token Issuers. The issuer claim from the subject token provided in the token exchange request must match one entry in this list.
  3. Configure the plugin with an HTTP Client. The HTTP Client is used to connect to the discovery endpoint of the token issuer. Make sure the Security Settings are configured restrictively and will only trust the certificate of the discovery endpoint.
  4. The Token Exchange server is ready to verify subject tokens.

Token Exchange server plugin - Token Exchange Rules list

  1. Configure at least one JWT Token Exchange Rule plugin.
  2. Configure a Requested Resource Or Audience Condition plugin with regex patterns to match the resource or audience parameters of the token exchange requests. If multiple JWT Token Exchange Rule plugins are configured, the first matching Requested Resource Or Audience Condition decides which JWT Token Exchange Rule will be used to generate the exchanged token.
  3. Configure Issued Token Type value and Token Validity Lifetime [s].
    The purpose of the Issued Token Type property is to inform the client about the token format issued by the Token Exchange server.
  4. Configure the standard claims:
    • Audience Claim
    • Subject Claim
    • Client Id Claim
  6. Optionally configure Custom Claims.
  7. Configure the scope handling in the Scope Claim property, by adding a JWT Scope Handling plugin. Choose the appropriate scope processor(s) in the Scope Processors list. It is possible to copy scopes from the subject token and from the request, or to add static scopes.
  8. Add a Signature to the token by configuring a JWT Access Token Private Key Signature plugin.
  9. A JWT Token Exchange Rule plugin is configured that will generate an exchanged token with data from the subject token, from the request or statically supplied.

Using scope policies in token exchange

  1. It is possible to apply a scope policy to determine the processing of request or subject token supplied scopes.

  2. Go to the JWT Token Exchange Rule plugin.
  3. Configure and edit a JWT Scope Handling plugin in the Scope Claim property.
  4. Choose the appropriate policy in the Scope Policy property. See the plugin doku for documentation of the supported policies.

Actor token and act claim

The Token Exchange server offers a number of configuration options to support delegation and impersonation semantics:

Configuring a simple act claim

  1. These instructions will add a simple string value to the act claim. This may be useful in a scenario where the purpose of the act claim is limited to logging.

  2. Go to the JWT Token Exchange Rule plugin.
  3. In the property Actor Token Validation, add either a validation or an extractor plugin. We recommended adding a validation plugin that verifies the signature on the token.
  4. In the property Actor Claim, configure and edit a String From Actor Token (OAuth 2.0 Token Exchange) plugin. In this plugin's property Actor Token Data Name, define the name of the claim from the actor token.

Configuring a structured act claim

  1. These instruction will add a structured value to the act claim. With repeated token exchanges, this structure will grow and show the history of all the actors that have requested a token exchange.

  2. Go to the JWT Token Exchange Rule plugin.
  3. In the property Actor Token Validation, add either a validation or an extractor plugin. We recommended adding a validation plugin that verifies the signature on the token.
  4. In the property Actor Claim, configure an Actor Claim from Actor Token plugin.