---
schema_version: "1"
id: 163400c2acec73c4a5a2ed5ab44c8433036cfa962c7dcecf83bb6db75b4090ec
title: OAuth 2.0 Access Token Enforcement Using Mule OAuth Provider Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-gateway/policies-included-oauth-access-token-enforcement.md
canonical_url: https://docs.mulesoft.com/mule-gateway/policies-included-oauth-access-token-enforcement
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 05d4f3aed2670db4eaceb6d407c1bc5b943721c00a99820a0c77c6379c0c6fa8
description: MuleSoft Documentation Site
latest: true
---
---
product: Mule Gateway
keywords: oauth, raml, token, validation, policy
---

# OAuth 2.0 Access Token Enforcement Using Mule OAuth Provider 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 Access Token Enforcement Using Mule OAuth Provider 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 Mule version available</strong></p></td><td><p>v4.1.1</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 Access Token Enforcement policy, which works exclusively with the Mule OAuth provider,
restricts access to a protected resource to only those HTTP requests that provide a valid OAuth 2
token belonging to a client application with API access. The policy does not generate tokens but
only validates them.

This policy is designed to be used exclusively with
[Mule OAuth provider](https://docs.mulesoft.com/api-manager/latest/mule-oauth-provider-landing-page). Using the policy with
any other OAuth 2.0 provider (for example, Facebook, Google, or Microsoft Azure) is not supported.

## Configuring Policy Parameters

### Mule Gateway

When you apply the policy to your API from the UI, these parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><p>Scopes</p></td><td><p>Displays a space-separated list of supported scopes.</p></td><td><p><code>READ</code>, <code>WRITE</code>, <code>READ and WRITE</code></p></td></tr><tr><td><p>Scope Validation Criteria</p></td><td><p>Determines if the token must contain all defined scopes or just one. The values are <code>Contains all scopes</code> and <code>Contains any scope</code>.</p></td><td><p>If the ‘Contains all scopes’ value is selected, the tokens with the scopes <code>READ</code> and <code>WRITE</code> are accepted. If the ‘Contains any scopes’ value is selected, the tokens with the scopes <code>READ</code>, <code>WRITE</code>, and <code>READ AND WRITE</code> are accepted.</p></td></tr><tr><td><p>Access Token validation endpoint url</p></td><td><p>The URL of the Access Token validation endpoint of the external OAuth 2 provider.</p></td><td><p>The link to a Mule provider hosted by the client: http://client-hostetd-mule-provider-url.cloudhub.io/validate.</p></td></tr><tr><td><p>Validate TLS Certificate</p></td><td><p>Enables third-party authentication server TLS validation.</p></td><td><p>If selected, the communication with the token validation endpoint uses the TLS protocol.</p></td></tr><tr><td><p>Expose Headers</p></td><td><p>In a proxy scenario, specifies whether headers must be exposed in the request to the backend. User properties returned by the federation server are prefixed with 'X-AGW-' and sent as headers to the backend.</p></td><td><p>See <a href="#leveraging-TVE-information">Leveraging Token Validation Endpoint Information for Mule Applications</a> for more information about this element.</p></td></tr><tr><td><p>Skip Client Id Validation</p></td><td><p>Skips the client application’s API contract validation.</p></td><td><p>If selected, Step 4 of the diagram in the <a href="#how-this-policy-works">How This Policy Works</a> section is skipped.</p></td></tr><tr><td><p>Authentication request timeout</p></td><td><p>Sets the maximum time, in milliseconds, to wait for a response when authenticating with the Access Token validation endpoint.</p></td><td><p><code>10000</code></p></td></tr></tbody></table>

## How This Policy Works

The following diagram illustrates the OAuth 2.0 Token Enforcement using Mule OAuth Provider policy
workflow:

![A flowchart illustrating the process of a user engaging with an API via an OAuth policy](/mulesoft/current/en-us/mule-gateway/_images/open-id-policy-workflow.png)

As shown in the diagram:

1.  The user first sends an HTTP request to the API protected by the policy.

2.  The policy extracts the token from the request and sends it to the validation endpoint to verify
    the integrity of the token.

3.  The token validation endpoint returns token metadata, including the client ID of the client
    application.

4.  Using a local database updated with contracts previously obtained from Anypoint Platform, the
    policy verifies whether the client ID has access to the API.

5.  If all the validations are successfully completed, the request is allowed to reach the backend.

### Leveraging Token Validation Endpoint Information for Mule Applications

When a token validation endpoint successfully validates a token, certain information, such as
configurable fields from Mule OAuth provider, are returned to the policy.

The following example illustrates the token validation response from the authorization server:

```text
---
{
    "uid":"john.doe",
    "mail":"john.doe@example.com"
    "token_type":"Bearer",
    "expires_in":3600,
    "alias" : ["Jhon", "Jhonny", "Mr Doe"],
    "address" : {
        "city": "london",
        "road": “abbey road"
    }
```

} --- The fields returned by the OAuth provider are processed by the policy, propagated throughout
the Mule flow, and finally exposed to the backend if the application requesting the access uses an
HTTP requester.

### Token Caching

After the system validates a token, that token is cached (by default), until it expires, thereby
improving the performance of the policy. In certain cases, such as in the case of revoked tokens,
you might want to minimize or even disable caching.

The validation endpoint sends multiple properties to the policy, including the expiration time of
the token. If the expiration information is not available, tokens are not cached.

To control the time taken to cache the tokens, before you attempt revalidating against the token
validation endpoint, specify the following property when starting Mule runtime engine:

`anypoint.platform.max_federation_expiration_time=<expiration time in seconds>`

Alternatively, you can specify this parameter in the `wrapper.conf` file. Setting this property
caches the token for the specified amount of time or until the tokens expire, whichever occurs
first. If you have enabled this property and the validation endpoint does not send the expiration
information, tokens are not cached.

To control the number of tokens that can be cached simultaneously, specify the following property
when starting Mule runtime engine:

`anypoint.platform.oauth2_cache_max_size=<amount of tokens to be cached; default value is 10.000; specify 0 to disable caching>`

Alternatively, you can specify this parameter in the `wrapper.conf` file.

## Configuring the Expose Headers Option

If you configured the `Expose Headers` option in the policy and if the application (for example,
out-of-the-box proxies) uses the HTTP requester, the properties are redirected to the backend as
headers.

For each field, the original request to the protected resource is enriched with the HTTP headers
using the format X-AGW- + <key>=<value>. For the example response from the previous section, the
following headers are added:

```text
---
X-AGW-uid=john.doe
X-AGW-mail=john.doe@example.com
X-AGW-token_type=Bearer
---
```

The propagated properties do not include the `scope` and `expires_in` objects and arrays.

For further processing within the flow, the original unparsed response from the validation endpoint
is made available. The information is stored in an authentication object.

For example, if a `mail` field is returned to the policy, you can access the value of this field by
using the following DataWeave 2.0 expression:

`#[authentication.properties.userProperties.mail]`

You can obtain the client ID of the OAuth2 token by using the following DataWeave 2.0 expression:

`#[authentication.principal]`

## Communicating with the Token Validation Endpoint Using a Proxy

You can enable the OAuth 2.0 Access Token Enforcement using Mule OAuth Provider policy to use the
gateway proxy settings by specifying the following property when starting Mule runtime engine:

`anypoint.platform.external_authentication_provider_enable_proxy_settings=<true|false(default)>`

When you enable this property, the policy uses the Mule proxy settings if you have configured the
following parameters:

- `anypoint.platform.proxy_host=localhost`

- `anypoint.platform.proxy_port=8080`

## FAQs

**Can I generate OAuth 2.0 tokens with the policy?**

No. The policy only validates the tokens.

**Can I use other OAuth providers with the policy?**

No. This policy is designed to work exclusively with the
[Mule OAuth provider](https://docs.mulesoft.com/api-manager/latest/mule-oauth-provider-landing-page). Using the policy with
any other OAuth provider (for example, Facebook, Google, or Azure) is not supported.

**What should I do if the Mule OAuth provider validation endpoint is rejecting the requests sent by
the policy?**

If the validation endpoint is rejecting requests, verify whether the URL configured in the policy is
reachable from the machine where the policy is running and that no authentication is required to
successfully complete the request. If your use case requires the validation endpoint to be
protected, you can switch to the
[Open ID Connect policy](https://docs.mulesoft.com/mule-gateway/policies-included-openid-token-enforcement).

**Where are the OAuth tokens cached?**

OAuth 2.0 tokens are cached only in memory and are never written to disk.

**Does the policy communicate with Anypoint Platform on a per-request basis?**

No, the policy uses client applications previously retrieved by Mule runtime engine. This enables
the policy to continue working even if the connection with the management plane is lost. If you want
the client application information that is written on disk to be encrypted,
[configure gateway encryption in your runtime](https://docs.mulesoft.com/mule-gateway/mule-gateway-encryption-mule4).

**Can I configure the Rate-Limiting SLA policy after I configure the OAuth 2.0 Access Token
Enforcement using Mule OAuth Provider policy?**

Yes, you can. Apply the Rate-Limiting SLA policy after the OAuth 2.0 access token enforcement using
Mule OAuth provider policy and provide a `Client ID Expression` value using the following DataWeave
2.0 expression:

`#[authentication.principal]`

Because the identity of the requester is already validated by the OAuth 2.0 Access Token Enforcement
using Mule OAuth Provider policy, you can leave the `Client Secret Expression` field empty.

**Where can I find the information associated with the token after it has been validated?** The
information is available in the authentication object. For more information, see
[Token Validation Endpoint Information for Mule Applications](#leveraging-TVE-information).

## See Also

- [Mule OAuth 2.0 Provider](https://docs.mulesoft.com/api-manager/latest/mule-oauth-provider-landing-page)

- [Mule 4.x HTTP Requester Connector](https://docs.mulesoft.com/http-connector/1.10/http-documentation)

- [Client Management for Federated Users and OpenID Connect Introspection Endpoint](https://docs.mulesoft.com/access-management/managing-api-clients)