Identity Gateway 7.2

OAuth2TokenExchangeFilter

Identifies a client’s access token or ID token (a subject token), and communicates with an authorization service, such as AM, to exchange it for a new token (an issued token):

  • When the OAuth2TokenExchangeFilter succesfully exchanges a token, it injects the issued token and its scopes into the OAuth2TokenExchangeContext.

  • When the OAuth2TokenExchangeFilter fails to exchange a token, it injects information about the failure into the OAuth2FailureContext, which is provided to the failureHandler.

The scopes for issued token can be restricted or expanded by the authorization services:

  • Restricted when the token scopes are a subset of those available to the subject token.

  • Expanded when they have scopes that are not included in the subject token.

Use this filter in the impersonation use case. For more information, see OAuth 2.0 Token Exchange in AM’s OAuth 2.0 guide.

Usage

{
  "name": string,
  "type": "OAuth2TokenExchangeFilter",
    "config": {
      "subjectToken": runtime expression<string>,
      "amService": AmService reference,
      "endpoint": configuration expression<url>,
      "subjectTokenType": configuration expression<string>,
      "requestedTokenType": configuration expression<string>,
      "scopes": [ runtime expression<string>, ... ] or ScriptableResourceAccess reference,
      "resource": configuration expression<url>,
      "audience": configuration expression<string>,
      "endpointHandler": Handler reference,
      "failureHandler": Handler reference
  }
}

Configuration

"subjectToken": runtime expression<string>, required

The location of the subject token in the inbound request.

"amService": AmService reference, required if endpoint is not configured

The AmService to use as the authorization service.

Configure either 'amService' or 'endpoint'. If both are configured, 'amService' takes precedence.

"endpoint": configuration expression<url>, required if amService is not configured

The URI for the authorization service.

Configure either 'amService' or 'endpoint'. If both are configured, 'amService' takes precedence.

"subjectTokenType": configuration expression<string>, optional

The subject token type.

Default: URN_ACCESS_TOKEN

"requestedTokenType": configuration expression<string>, optional

The type of token being requested.

Default: URN_ACCESS_TOKEN

"scopes": array of runtime expression<strings> or ScriptableResourceAccess <reference>, required

A list of one of more scopes required by the OAuth 2.0 access token.

array of runtime expression<strings>, required if ScriptableResourceAccess is not used

A string, array of strings, runtime expression<string>, or array of runtime expression<string> to represent one or more scopes.

ScriptableResourceAccess <reference>, required if "array of runtime expression<strings>" is not used

A script that produces a list of one or more scopes.

The script evaluates each request dynamically and returns the scopes that request needs to access the protected resource. The script must return a Promise<Set, ResponseException> or a Set<String>.

For information about the properties of ScriptableResourceAccess, see Scripts.

{
  "name": string,
  "type": "ScriptableResourceAccess",
  "config": {
    "type": configuration expression<string>,
    "file": configuration expression<string>, // Use either "file"
    "source": [ string, ... ],                // or "source", but not both.
    "args": object,
    "clientHandler": Handler reference
  }
}

Default: Empty

"resource": configuration expression<url>, optional

The target service URI where the issued token is intended to be used.

"audience": configuration expression<url>, optional

The target service name where the token is intended to be used.

"endpointHandler": Handler reference, optional

The handler to exchange tokens on the authorization endpoint.

Configure this property as a Chain, using one of the following filters for client authentication:

{
  "name": "EndpointHandler",
  "type": "Chain",
  "config": {
    "handler": "ForgeRockClientHandler",
    "filters": [
      {
        "type": "ClientSecretBasicAuthenticationFilter",
        "config": {
          "clientId": "serviceConfidentialClient",
          "clientSecretId": "client.secret.id",
          "secretsProvider" : "SystemAndEnvSecretStore-1",
        }
      }
    ]
  }
}

Default: ForgeRockClientHandler

"failureHandler": Handler <reference>, optional

Handler to manage a failed request.

Provide an inline handler configuration object, or the name of a handler object declared in the heap. The handler can access information in the OAuth2FailureContext.

Default: 500 Internal Server Error, the request stops being executed.

Example

For an example of how this filter is used, see OAuth 2.0 token exchange.

More information

org.forgerock.http.oauth2.OAuth2TokenExchangeFilter

OAuth2TokenExchangeContext

OAuth2FailureContext

The OAuth 2.0 Authorization Framework