OAuth 2.0 Token Introspection Policy

Policy Name

Summary

Allows access only to authorized client applications

Category

Security

First Flex Gateway version available

v1.3.0

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.

Configuring Policy Parameters

Flex Gateway

To apply OAuth 2.0 token introspection when using Flex Gateway as your runtime, you must manually configure the policy in a YAML configuration file. 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

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

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

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