About OpenAM, OpenID Connect, or PingFederate OAuth Token Enforcement Policies

The authorization enforcement policy, which you apply to an API in Anypoint Platform, connects to an OpenAM authorization server, an OpenID Connect Token Introspection endpoint, 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.

PingFederate and OpenAM OAuth Clients and Grant Types

OpenAM supports two types of OAuth clients:

A Confidential Client keeps its credentials confidential and includes the following grant types:
- Client Credentials
- Implicit
- Password
A Public Client shares its credentials with other parties and includes the following grant types:
- Authorization Code
- Implicit
- Password

Each type of client supports three of the four OAuth grant types. For this reason, when configuring the OpenAM client, you can select only three of the four grant types. The other grant type is unavailable because it belongs to the other client. You determine the public or confidential property of the OpenAM client depending on the grant types you select.

A PingFederate client allows any combination of 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.

User Verification

The API can include a check of the credentials of the user requesting the access token. Use MEL expressions to access a map of user information that is associated with the valid token. Use the flow variable ['_agwUser']. To access a particular value in the map, specify it directly.

This example accesses the user ID of the end user who is calling the API through the application:

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

'_agwUser' Map Key	Description
uid	User ID of the end user who is calling the API through the application.
group	An array of groups with which the user is associated.
email	The email of the user.

'_agwUser' Map Key

Description

uid

User ID of the end user who is calling the API through the application.

group

An array of groups with which the user is associated.

email

The email of the user.

Obtaining User Credentials

The policy returns a Mule message that includes outbound properties that provide information about what externally authenticated users or applications are using your API. Depending on the grant type of the incoming request token, this is expressed in different headers:

If the token of the request is of Grant types resource owner credentials, implicit, or authorization code, the header X-AGW-userid contains the ID of the user that made the request.
If the token of the request is of Grant type client credentials, the header X-AGW-client_id contains the ID of the application that made the request.

Either of the two properties are available to be referenced and used internally in your proxy by any component that follows it in the flow.

The HTTP Connector that generates the proxy output transforms any received outbound properties in the HTTP message headers. The message that reaches your API after passing through your proxy includes one of the following HTTP headers:

X-AGW-userid with the username
X-AGW-client_id with a client ID

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"}

Policy Implementation

This diagram shows how the policy works with an existing OpenAM or PingFederate authorization server, 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 PingFederate 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 an error. For example:

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