Mule OAuth 2.0 Provider

Mule OAuth 2.0 Provider is an OAuth 2.0 provider alternative developed by MuleSoft that can be used in any MuleSoft API Platform organization, including the federated ones.

You must deploy Mule OAuth 2.0 Provider to a runtime with API gateway capabilities, for example, Mule runtime engine (Mule) 3.x, 4.2.0, or later, with the corresponding organization credentials. The following third party OAuth 2.0 providers are supported:

PingFederate
OpenAM
OAuth 2.0 providers supporting Open ID Connect

The Mule OAuth 2.0 Access Token Enforcement policy is designed to work with Mule OAuth 2.0 Provider.

Downloading Mule OAuth 2.0 Provider

You can download Mule OAuth 2.0 Provider from Anypoint Exchange:

Mule 3.x: See External OAuth 2.0 server for Anypoint Platform.
Mule 4.x: See Mule OAuth 2.0 server for Anypoint Platform.

This feature is available in Mule 4.2.0 and later.

OAuth 2.0 Dance

The authentication performed by the OAuth 2.0 provider, API, and client application conforms to RFC 6749. This authentication process is known as the OAuth 2.0 dance.

Mule OAuth 2.0 Provider supports all grant types. The entity that requests access to a resource protected by the Mule OAuth 2.0 Access Token Enforcement policy is a Client.

Endpoints

You can call the following Mule OAuth 2.0 Provider endpoints in your API implementation:

Purpose	Default Path	Description
Token validation	/validate	Used to verify the validity of the token: whether the token is expired, revoked or fake. You can define more than one validation endpoint, each of them enforcing different scopes. For more information, see <Scopes>.
Authorization	/authorize	Used to obtain a token when the client is running in a browser using a scripting language or when the client is a web server.
Access	/access_token	Used when the client is owned by the same entity as Mule OAuth 2.0 Provider or when the client is the same entity as the protected resource owner.
Token revocation	/revoke	[Optional] Used to revoke a valid token to render it invalid.

Purpose

Default Path

Description

Token validation

/validate

Used to verify the validity of the token: whether the token is expired, revoked or fake. You can define more than one validation endpoint, each of them enforcing different scopes. For more information, see <Scopes>.

Authorization

/authorize

Used to obtain a token when the client is running in a browser using a scripting language or when the client is a web server.

Access

/access_token

Used when the client is owned by the same entity as Mule OAuth 2.0 Provider or when the client is the same entity as the protected resource owner.

Token revocation

/revoke

[Optional] Used to revoke a valid token to render it invalid.

Implementing Scopes

The OAuth 2.0 scopes enable you to further limit access to a resource protected by OAuth. You can define words, such as READ and WRITE, or others specific to your organization, such as CONTRACTOR, PUBLIC, EMPLOYEES_ONLY, and so on.

You can define scopes in three different places:

In the universal set definition, defaultScopes, where you define all possible scopes:

<oauth2-provider:config
  scopes="CONTRACTOR, PUBLIC_READ, EMPLOYEES_ONLY, WRITE"
  >
  ...
</oauth2-provider:config>

In the /validate validation endpoint, to enforce a particular subset of the previously defined scopes.
In the Mule OAuth 2.0 Access Token Enforcement policy, where you can enforce scopes by specifying a space-separated list.

Specifying more than one scope enforces the AND logic. If the token to be validated is associated with all of the requested scopes, the policy validates the token successfully.

Example of using scopes in Mule 4.2.x or later:

...
    <oauth2-provider:config name="external-oauth2-provider"
    							resourceOwnerSecurityProvider="resourceOwnerSecurityProvider"
    							clientSecurityProvider="clientSecurityProvider"
    							supportedGrantTypes="AUTHORIZATION_CODE,IMPLICIT,RESOURCE_OWNER_PASSWORD_CREDENTIALS,CLIENT_CREDENTIALS"
    							listenerConfig="https.listener"
    							scopes="CONTRACTOR, PUBLIC_READ, EMPLOYEES_ONLY, WRITE"
                                defaultScopes="CONTRACTOR, PUBLIC_READ, EMPLOYEES_ONLY, WRITE"
                                clientStore="clientObjectStore">
    		<oauth2-provider:token-config path="/access-token" tokenTtl="5" tokenTtlTimeUnit="SECONDS" tokenStore="tokenObjectStore">
                <oauth2-provider:refresh-token-strategy>
                    <oauth2-provider:single-refresh-token objectStore="refreshTokenObjectStore"/>
                </oauth2-provider:refresh-token-strategy>
            </oauth2-provider:token-config>
    		<oauth2-provider:authorization-config path="/authorize" authorizationCodeStore="authorizationCodeObjectStore"/>
    	</oauth2-provider:config>

        <flow name="validateToken">
            <http:listener path="/validate" config-ref="https.listener"/>
            <oauth2-provider:validate-token scopes="#[['PUBLIC_READ']]" config-ref="external-oauth2-provider" accessToken="#[attributes.queryParams.access_token]"/>
            <error-handler>
                <on-error-continue type="OAUTH2-PROVIDER:TOKEN_UNAUTHORIZED">
                    <set-payload value="UNAUTHORIZED_TOKEN"/>
                </on-error-continue>
            </error-handler>
        </flow>
...

For complete information, see Mule OAuth 2.0 Server for Anypoint Platform.

Client Application Cache

To prevent any possible downtime of Mule OAuth 2.0 Provider due to errors when connecting to Anypoint Platform, the Mule OAuth client store caches each valid client application for which a token is requested.

In the rare instance that the provider requests a new token when there is no connection available, the client store falls back to cache. The entries expire in 30 days, which is the default setting. To ensure service availability in case of a restart or lack of connection to Anypoint Platform, you can configure this range to persist the cache locally.

In case a client application for which a token already exists in the client store is removed from Anypoint Platform, the client store removes the client from the cache on the next token request, mirroring the platform status. The mechanism that caches the result of a successful token validation is part of the Mule OAuth 2.0 Access Token Enforcement policy.

Customizing the Client Application Cache Mechanism

You can customize the default values of the cache mechanism in Mule 4.2.0 and later. The object store has two configurable properties:

Property Name Definition

Property Name	Definition
`anypoint.oauth_provider.cache_persistence_enabled`	Defines whether the caching mechanism must persist locally. The default value is `true` if the property is not set or cannot be parsed. Cache persistence allows client authorization without connection to Anypoint Platform.
`anypoint.oauth_provider.cache_ttl_days`	Represents how many days each client application must be cached by the OAuth Server. You can specify any positive floating-point number for this value. The default value is `30`, representing 30 days.

anypoint.oauth_provider.cache_persistence_enabled

Defines whether the caching mechanism must persist locally. The default value is true if the property is not set or cannot be parsed. Cache persistence allows client authorization without connection to Anypoint Platform.

anypoint.oauth_provider.cache_ttl_days

Represents how many days each client application must be cached by the OAuth Server. You can specify any positive floating-point number for this value. The default value is 30, representing 30 days.