OpenID Connect, OpenAM, or PingFederate OAuth Token Enforcement Policies

The authorization enforcement policy, which you apply to an API in Anypoint Platform, connects to an an OpenID Connect Token Introspection endpoint, OpenAM authorization server, or a PingFederate authorization server. The policy enforces access according to the configuration of the following things:

Scope of access (optional)
OAuth clients
The proxy connection to the authorization server

To apply the policy to an API, use the general procedure for applying policies. You configure scope of access as you apply the policy.

In addition to configuration tasks, you can implement verification of the credentials of the user requesting an access token.

Prerequisites

Your Anypoint Platform organization is setup as a federated organization using either OpenAM, OpenID Connect, or PingFederate.
You are an Anypoint Platform organization administrator or have permission to create or manage APIs.

Policy Implementation

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

1 Authorize app to access API 2 Send user credentials 3 Send valid token 4 Call API 5 Check scope and token in header/parameter 6 Validate token in header/parameter and scope 7 API is called

First, the client application requests the token directly from the authorization server before making an API call. The client application makes this request by authenticating with user credentials.
The server supplies the client application with a valid token.
Next, the client application sends the valid token in the API call.
Mule, governed by the OpenAM, OpenID Connect, or OAuth Token Enforcement policy, checks that the token in the header or query parameter is valid and matches the correct scopes.
The policy invokes the OpenAM authorization server, OpenID Connect Token Introspection endpoint, or PingFederate authorization server to validate the token and check scopes.
Finally, the API receives the call from the client application.

To improve performance, Mule caches the call to the authorization server, which is only performed once during the lifetime of the token. If the OAuth token is not valid, the authorization server returns an error. For example:

OpenAM 11.0.0 returns 404 NOT FOUND
OpenAM 12.0.0 returns 400 BAD REQUEST
PingFederate returns 403 FORBIDDEN

Configuring OpenAM OAuth Clients and Grant Types

OpenAM supports two kinds of OAuth clients:

confidential client

Keeps its credentials confidential
public client

Shares its credentials with other parties.

Each type of client supports three of the four OAuth grant types. For this reason, when configuring Mule 3.8 or later, or the legacy API Gateway, for the OpenAM client, you are able to select only three of the four grant types. The other grant type is unavailable. You determine the public or confidential property of the OpenAM client depending on the grant types that you select.

Configuring PingFederate OAuth Clients and Grant Types

A PingFederate client supports all four OAuth grant types: Implicit, Client Credentials, Resource Owner Password Credentials, and Authorization Code. As a PingFederate user, you can enable or disable grant types in any order you want.

Obtaining User Credentials

Federation policies enrich the flow with user information stored in the OAuth Provider that can be used for user verification. This information is accessible from attributes.headers in Mule 4 or higher or outbound properties in earlier version. The elements that provide the information depend on the grant type used to retrieve the token.

The user ID is X-AGW-userid for these grant types:
- Resource Owner Credentials
- Implicit
- Authorization Code
The user ID is X-AGW-client_id for the Client Credentials grant type.

This information is available to be referenced and used internally in your proxy by any component that follows it in the flow.

All user information enriched by the policy has the "X-AGW-" prefix.

Deployments under Mule 3.x and Earlier

The HTTP Connector that generates the proxy output transforms any received outbound properties into HTTP message headers that were returned to the requester. User information can be accessed from a map. Use MEL expressions to access the flow variable that contains the map ['_agwUser']. If you want to access a particular value of the map you could use this expression, for example:

#[flowVars['_agwUser']['uid']]

Deployments under Mule 4

Policies that are called after the federated OAuth 2 policy, or in a flow, can use the Authentication.properties object. This object contains the following elements:

Raw response message

#[authentication.properties.tokenContext]
Access Token

#[authentication.properties.accessToken]
OAuth Provider response headers

#[authentication.properties.userProperties]

If you configure the policy to expose headers, information from this object arrives at the backend API as headers.

Token Validation Response Example

The following example shows the information returned that forms the HTTP message headers.

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":"john.doe@example.com","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"}