PingGateway 2024.11

TokenIntrospectionAccessTokenResolver

In OAuth2ResourceServerFilter, use the token introspection endpoint, /oauth2/introspect, to resolve access tokens and retrieve metadata about the token. The endpoint typically returns the time until the token expires, the OAuth 2.0 scopes associated with the token, and potentially other information.

The introspection endpoint is defined as a standard method for resolving access tokens, in RFC-7662, OAuth 2.0 Token Introspection.

Usage

Use this resolver with the accessTokenResolver property of OAuth2ResourceServerFilter.

"accessTokenResolver": {
  "type": "TokenIntrospectionAccessTokenResolver",
  "config": {
    "amService": AmService reference,          // Use either "amService"
    "endpoint": configuration expression<url>, // or "endpoint", but not both.
    "providerHandler": Handler reference
  }
}

Properties

"amService": AmService reference, required if endpoint isn’t configured

The AmService heap object to use for the token introspection endpoint. The endpoint is extrapolated from the url property of the AmService.

When the Authorization Server is AM, use this property to define the token introspection endpoint.

If amService is configured, it takes precedence over endpoint.

See also AmService.

"endpoint": configuration expression<url>, required if amService isn’t configured

The URI for the token introspection endpoint. Use /oauth2/introspect.

When the Authorization Server is not AM, use this property to define the token introspection endpoint.

If amService is configured, it takes precedence over endpoint.

"providerHandler": Handler reference, optional

Invoke this HTTP client handler to send token info requests.

Provide either the name of a Handler object defined in the heap or an inline Handler configuration object.

Default: ForgeRockClientHandler

If you use the AM token introspection endpoint, this handler can be a Chain containing a HeaderFilter to add the authorization to the request header, as in the following example:

"providerHandler": {
  "type": "Chain",
  "config": {
    "filters": [
      {
        "type": "HeaderFilter",
        "config": {
          "messageType": "request",
          "add": {
            "Authorization": [ "Basic ${encodeBase64('<client_id>:<client_secret>')}" ]
          }
        }
      }
    ],
    "handler": "ForgeRockClientHandler"
  }
}

Example

You can find an example route that uses the token introspection endpoint in Validate access tokens with introspection.

More information

org.forgerock.openig.filter.oauth2.TokenIntrospectionAccessTokenResolverHeaplet

OAuth2ResourceServerFilter