PingFederate, OpenAM, or OpenID Connect OAuth Token Enforcement Policies

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

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, OpenID Connect, or PingFederate authorization server 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

Configuring Scope of Access

You optionally fill in the scopes field when you apply the policy to your API version in Anypoint Platform. Enter a space-separated list of strings that indicate the scopes to which applications must have access per their credentials defined for that application in OpenAM. You need to know the names of the scopes as defined in OpenAM, OpenID Connect or PingFederate. Scope names are case-sensitive.

Assuming you have deployed the API, to configure scopes:

In API Manager, navigate to the API dashboard of your API, and click Policies.
Click Apply.
In the Configure PingFederate OAuth Token Enforcement Policy dialog, enter a space-separated list of strings that indicate the scope of application access to your API. This access needs to correspond to credentials defined for applications in OpenAM or PingFederate.

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.

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