OAuth2TokenExchangeFilter

Identifies a client’s subject token representing the party requesting the action and an optional actor token representing the party acting on their behalf. This filter communicates with an authorization service to exchange it for a new token, called an issued token:

When the OAuth2TokenExchangeFilter successfully 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 aren’t included in the subject token.

Use this filter in impersonation and delegation use cases. Learn more in the AM documentation on Token Exchange.

Usage

{
  "name": string,
  "type": "OAuth2TokenExchangeFilter",
    "config": {
      "subjectToken": runtime expression<string>,
      "amService": AmService reference,
      "endpoint": configuration expression<url>,
      "actorToken": runtime expression<string>,
      "actorTokenType": configuration expression<string>,
      "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" isn’t 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" isn’t configured

The URI for the authorization service.

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

"actorToken": runtime expression<string>, optional

The location of the actor token in the inbound request.

When you configure this property, PingGateway sends actor_token and actor_token_type to the authorization service for a delegation exchange.

If the expression evaluates to null, the filter calls the failureHandler with an invalid_request error.

This feature requires PingGateway 2026.9 or later.

"actorTokenType": configuration expression<string>, optional

The type of the actor token.

PingGateway ignores this property when actorToken isn’t configured.

Default: urn:ietf:params:oauth:token-type:access_token

This feature requires PingGateway 2026.9 or later.

"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 ResourceAccess <reference>, required

A list of one or more scopes required by the OAuth 2.0 access token. Provide the scopes as strings or through a ResourceAccess such as a ScriptableResourceAccess:

Array of runtime expression<strings>, required if a ResourceAccess isn’t used: A string, array of strings, runtime expression<string>, or array of runtime expression<string> to represent one or more scopes.

ScriptableResourceAccess <reference>

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

For information about the properties of ScriptableResourceAccess, refer to PingGateway 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

You can find an example of how this filter is used in OAuth 2.0 token exchange with PingAM.

More information

org.forgerock.http.oauth2.OAuth2TokenExchangeFilter

OAuth2TokenExchangeContext

OAuth2FailureContext

The OAuth 2.0 Authorization Framework