Contact Free trial Login

OAuth 2 Policy Implementation

The following diagram shows how the OAuth 2 policy works with an existing OpenAM or PingFederate authorization server, or OpenID Connect Token Introspection endpoint, to protect access to your API version.

oauth implementation federated
  1. The user or application requests an access token using any valid grant type defined in the client application.

  2. The user or application sends a request with the access token. The federated policy validates the access token, provided as a well-formed query param or authorization header.

  3. The federated policy validates the token against the OAuth provider. To improve performance, Mule caches the call to the authorization server, which is only performed once during the lifetime of the token.

    When OpenId, PingFederate, or OAuth 2.0 Access Token Enforcement Using External Provider policies are in effect and your API is deployed under Mule 4, the client ID returned by the OAuth provider is validated by the Client Id Enforcement policy.

  4. As opposed to Mule 3, in Mule 4, all fulfilled requests in the flow are enriched with the information provided by the OAuth Provider, but this information is not returned to the user unless explicitly configured in the policy by enabling the Expose Headers checkbox:

    oauth policy implementation concept 7ad82

    The following example shows HTTP message headers returned as a token validation response.

    HTTP/1.1 200 OK
    Cache-Control: no-cache, no-store
    Date: Mon, 09 Mar 2015 19:08:07 GMT
    Accept-Ranges: bytes
    Server: Restlet-Framework/2.1.1
    Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
    Content-Type: application/json;charset=UTF-8
    Transfer-Encoding: chunked
    {"uid":"john.doe","mail":"","scope":["uid","mail","cn","givenName"],"grant_type":"password","cn":"John Doe Full","realm":"/","token_type":"Bearer","expires_in":580,"givenName":"John","access_token":"fa017a0e-1bd5-214c-b19d-03efe9f9847e"}

    This token validation response may vary and, if Expose Headers is enabled, the proxy sends all headers received to the backend implementation with the exceptions of scope, expires_in nodes, and the x-rate-limit headers (x-ratelimit-remaining, x-ratelimit-limit, and x-ratelimit-reset).

Possible responses are:

Response Reason


The token was successfully validated.


This Bad Request error can be caused by: no token sent, the token was sent both as query param and header, or the token was sent as header but does not have prefix "Bearer".


The token is unauthorized.


This response code can be caused by an error in the validation to the OAuth Provider, the scopes validation, or the Client ID Enforcement Policy.

Mule 4 Implementation Scenarios

Below are a series of diagrams showing the most common implementation scenarios:

Successfully Validated Tokens

The following diagram represents a successfully validated token for OpenId, PingFederate, and OAuth 2.0 Access Token Enforcement Using External Provider policies:

oauth implementation diagram2

The following diagram represents a successfully validated token for OpenAM policy:

successful validated openam

Unauthorized Token

The following diagram represents an Unauthorized (401) Token error:

unauthorized token


The following diagram represents a Forbidden (403) Error from OAuth Provider error:

forbidden error

Invalid Scopes

The following diagram represents Invalid Scopes error:

invalid scopes

Failed Client ID Enforcement Validation

The following diagram represents a Client ID Enforcement Validation Failed error:

oauth implementation diagram3

This error is not valid for OpenAM Policy

Bad Request

The following diagram represents a Bad Request (400) error:

bad request

Failed TLS Certificate Validation

The following diagram represents the TLS Certificate Validation error:

federation tls error

Mule 4 HTTP Headers

Federation policies add extra headers to the HTTP request containing user properties returned by the federation server when validating the access token. These headers are identified with the x-agw-* prefix, and since they are only set for outgoing HTTP requests, other policies applied after the federation policy are not able to receive these special headers.
For example, if you have an OpenId Connect Access Token Enforcement policy that sets the x-agw-uid header, other policies won’t be able to extract this header.
You can use DataWeave to retrieve the user information returned by the federation server.

For example, to retrieve the user name passed in x-agw-username, use:


To retrieve the UID passed in x-agw-uid, use:


User properties vary depending on your federated implementation. As a regular rule of thumb, you can get the value for a specific X-AGW-{key}=value header, using the expression #[{key}].
Additionally, the expression [*] returns all the claims discovered by our introspection endpoint.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub