---
schema_version: "1"
id: f35a977cd4c27a0a3d9763b819bfce47871b563f39c99b4d76d7ee2a3cf475b4
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/latest/policies-included-oauth-token-introspection.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-included-oauth-token-introspection
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 2cee76199783447ab0bd1ada2e77dfe66d49649c3ad25bbb80be24d3af1bb379
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
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
```