OAuth 2.0 Token Introspection Policy

Policy Name

Summary

Allows access only to authorized client applications

Category

Security

First Omni Gateway version available

v1.3.0

Release Notes

OAuth 2.0 Token Introspection Policy

Returned Status Codes

400 - Invalid token

401 - Unauthorized access or error when connecting to the authorization server

403 - Forbidden, invalid client application credentials

500 - Bad response from authorization server, or WSDL SOAP fault error

Summary

The OAuth 2.0 Token Introspection policy enables you to configure OAuth 2.0 using any third-party Identify Provider (IdP), such as Okta, AWS, Azure or Google Cloud Platform. The policy allows for tokens based on the OAuth 2.0 Authorization Framework to be authorized without having to register an external IdP server in the Anypoint Platform.

The policy validates the token sent by the client to the protected API, and allows access to the backend server only if the introspection endpoint authorizes the token.

OAuth Introspection Policy doesn’t support Microsoft Entra ID because Microsoft Entra ID doesn’t provide an introspection endpoint.

Configuring Policy Parameters

Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

- policyRef:
    name: oauth2-token-introspection-flex
  config:
    introspectionURL: <string> // REQUIRED
    authorizationValue: <string> // REQUIRED
    validatedTokenTTL: <number> // OPTIONAL
    authenticationTimeout: <number> // OPTIONAL
    skipClientIdValidation: <boolean> // REQUIRED
    consumerBy: <string> // REQUIRED
    exposeHeaders: <boolean> // OPTIONAL
    scopes: <string> // OPTIONAL
    scopeValidationCriteria: <string> // OPTIONAL
    maxCacheEntries: <number> // OPTIONAL
    enableProtectedResourceMetadata: <boolean> // OPTIONAL
    overrideProtectedResourceMetadataAuthorizationServerUrl: <boolean> // OPTIONAL
    protectedResourceMetadataAuthorizationServerUrl: <string> // OPTIONAL

Parameter Required or Optional Default Value Description

Parameter	Required or Optional	Default Value	Description
`introspectionURL`	Required		The third-party token introspection URL
`authorizationValue`	Required		The method to request authorization from the authentication service. Specify either a Basic Auth string with `client_id` and `client_secret`, or a Bearer Token.
`validatedTokenTTL`	Optional	600	The caching limit for the validated token
`authenticationTimeout`	Optional	10000	The timeout when sending data to the authentication service
`skipClientIdValidation`	Required	false	Enables/disables client ID enforcement support
`consumerBy`	Required		Associate an identity provider’s `username` or `client_id` response with a registered platform’s `client_id`. Required if skip_client_id_validation`is `true.
`exposeHeaders`	Optional	false
`scopes`	Optional	""	A space-delimited list
`scopeValidationCriteria`	Optional	"AND"	The criteria to apply to the `scopes` values. Valid parameter values are "AND" or "OR".
`maxCacheEntries`	Optional	1000
`enableProtectedResourceMetadata`	Optional	false	Enables RFC 9728 OAuth 2.0 Protected Resource Metadata. When `true`, all `401` responses include a `WWW-Authenticate` header with the resource metadata URL `{api_path}/.well-known/oauth-protected-resource`. When a client makes a GET request to this path, Omni Gateway responds with a JSON document containing the authorization server metadata. By default, Omni Gateway derives the authorization server URL supplied in the metadata from the introspection endpoint URL. For example, `https://auth.example.com/introspect` becomes `https://auth.example.com`.
`overrideProtectedResourceMetadataAuthorizationServerUrl`	Optional	false	Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.
`protectedResourceMetadataAuthorizationServerUrl`	Optional		Server base URL to use when `overrideProtectedResourceMetadataAuthorizationServerUrl` is `true`.

introspectionURL

Required

The third-party token introspection URL

authorizationValue

Required

The method to request authorization from the authentication service. Specify either a Basic Auth string with client_id and client_secret, or a Bearer Token.

validatedTokenTTL

Optional

600

The caching limit for the validated token

authenticationTimeout

Optional

10000

The timeout when sending data to the authentication service

skipClientIdValidation

Required

false

Enables/disables client ID enforcement support

consumerBy

Required

Associate an identity provider’s username or client_id response with a registered platform’s client_id. Required if skip_client_id_validation`is `true.

exposeHeaders

Optional

false

scopes

Optional

A space-delimited list

scopeValidationCriteria

Optional

"AND"

The criteria to apply to the scopes values. Valid parameter values are "AND" or "OR".

maxCacheEntries

Optional

1000

enableProtectedResourceMetadata

Optional

false

Enables RFC 9728 OAuth 2.0 Protected Resource Metadata. When true, all 401 responses include a WWW-Authenticate header with the resource metadata URL {api_path}/.well-known/oauth-protected-resource.
When a client makes a GET request to this path, Omni Gateway responds with a JSON document containing the authorization server metadata. By default, Omni Gateway derives the authorization server URL supplied in the metadata from the introspection endpoint URL. For example, https://auth.example.com/introspect becomes https://auth.example.com.

overrideProtectedResourceMetadataAuthorizationServerUrl

Optional

false

Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.

protectedResourceMetadataAuthorizationServerUrl

Optional

Server base URL to use when overrideProtectedResourceMetadataAuthorizationServerUrl is true.

Resource Configuration Example

- policyRef:
    name: oauth2-token-introspection-flex
  config:
    introspectionURL: https://my-introspection.com/introspect
    authorizationValue: Basic am9obkBleGFtcGxlLmNvbTphYmMxMjM=
    validatedTokenTTL: 600
    authenticationTimeout: 10000
    skipClientIdValidation: false
    consumerBy: "client_id"
    exposeHeaders: true
    scopes: "profile email shopping"
    scopeValidationCriteria: "AND"
    maxCacheEntries: 1000