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, refer to 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 ifendpointis 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 ifamServiceis 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, refer to 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, refer to OAuth 2.0 token exchange.