---
schema_version: "1"
id: ade9ec1d214c112e080b671cd748db6fa1baef62d59c599bb3bd3da93eb73ef8
title: OAuth 2.0 Token Introspection Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-oauth-token-introspection.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-oauth-token-introspection
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 6de53c69f03981d03145c345893c1ba4b9e71572be7ebb49ceb5b3548d4b580a
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: oauth, token, validation, introspection, policy
---

# OAuth 2.0 Token Introspection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 Token Introspection Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.3.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-token-introspection-release-notes">OAuth 2.0 Token Introspection Policy</a></p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP fault error</p></td></tr></tbody></table>

## 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.

> [!NOTE] 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

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>introspectionURL</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The third-party token introspection URL</p></div></div></td></tr><tr><td><div><div><p><code>authorizationValue</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The method to request authorization from the authentication service. Specify either a Basic Auth string with <code>client_id</code> and <code>client_secret</code>, or a Bearer Token.</p></div></div></td></tr><tr><td><div><div><p><code>validatedTokenTTL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>The caching limit for the validated token</p></div></div></td></tr><tr><td><div><div><p><code>authenticationTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>The timeout when sending data to the authentication service</p></div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables client ID enforcement support</p></div></div></td></tr><tr><td><div><div><p><code>consumerBy</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>Associate an identity provider’s <code>username</code> or <code>client_id</code> response with a registered platform’s <code>client_id</code>. Required if <code>skip_client_id_validation`is `true</code>.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>scopes</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div><div><p>A space-delimited list</p></div></div></td></tr><tr><td><div><div><p><code>scopeValidationCriteria</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"AND"</p></div></div></td><td><div><div><p>The criteria to apply to the <code>scopes</code> values. Valid parameter values are "AND" or "OR".</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>enableProtectedResourceMetadata</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables <a href="https://www.rfc-editor.org/rfc/rfc9728">RFC 9728</a> OAuth 2.0 Protected Resource Metadata. When <code>true</code>, all <code>401</code> responses include a <code>WWW-Authenticate</code> header with the resource metadata URL <code>{api_path}/.well-known/oauth-protected-resource</code>.<br>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, <code><a href="https://auth.example.com/introspect">https://auth.example.com/introspect</a></code> becomes <code><a href="https://auth.example.com">https://auth.example.com</a></code>.</p></div></div></td></tr><tr><td><div><div><p><code>overrideProtectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.</p></div></div></td></tr><tr><td><div><div><p><code>protectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div></div></td><td><div><div><p>Server base URL to use when <code>overrideProtectedResourceMetadataAuthorizationServerUrl</code> is <code>true</code>.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- 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
```