Nav

OAuth 2.0 Access Token Enforcement Using External Provider Policy

You can use the OAuth 2.0 Access Token Enforcement Using External Provider policy to secure an API from client apps that try to access the API. To access resources on an OAuth2 authentication server, such as the Github authenication server outside Anypoint Platform, from a Mule client app configure authentication in the HTTP Requester connector of your app.

The documentation about the OAuth 2.0 Access Token Enforcement Using External Provider policy covers the following topics:

Like other API Manager-enforced policies, the API needs to be registered in API Manager to apply this policy.

You can restrict access to your API service on Anypoint Platform by applying the OAuth 2.0 Access Token Enforcement Using External Provider policy. This policy enforces the OAuth interaction, called the OAuth dance, between the OAuth 2.0 provider, API, and client application as described in RFC 6749. You can get a hands-on perspective of the OAuth dance by following the step-by-step procedure to build, run, and test the custom Mule OAuth provider in Anypoint Platform.

oauth+policy1
  1. The client application requests a token from the provider.

  2. The provider returns a token.

  3. The client application includes the token either as an authentication header or a query parameter in a request to the API.

  4. The OAuth 2.0 Access Token Enforcement Using External Provider Policy intercepts this request and communicates with the provider to validate the token.

  5. The validated token is whitelisted and kept on record until expiration. Any further requests that contain this token are not validated against the OAuth provider.

  6. If the token is valid, the request is forwarded to the API.

  7. The API responds to the client application.

The OAuth is secure because the client application gets authorization from an OAuth provider instead of directly gaining access to the user’s credentials. The user owns the credentials and authorizes the provider to interact with the API. The application has knowledge of the user’s authentication in the form of an access token.

Prerequisites

Prerequisites for using the OAuth 2.0 Access Token Enforcement Using External Provider policy are:

Requirements for RAML APIs

If the API protected by the OAuth 2.0 Access Token Enforcement Using External Provider policy is defined using RAML (recommended), define RAML securitySchemes for OAuth 2.0. The example of testing the custom provider from MuleSoft Consulting provides this RAML code. Within the RAML securitySchemes definition, you include URIs for the authorization and access token as shown in the example.

You specify grant types in RAML securitySchemes. The following example RAML syntax shows the authorizationGrants setting:

settings:
   authorizationUri: https://oauth2provider.cloudhub.io/authorize
   accessTokenUri:  https://oauth2provider.cloudhub.io/access_token
   authorizationGrants: [authorization_code, password, client_credentials, implicit]

The following table shows the mapping of the RAML grant types to the grant type names in the OAuth 2.0 Token Validation policy configuration. 

Authorization Grant Types Defined in RAML Definition Equivalent Authorization Grant Type to Enable in the OAuth Provider Policy Supported in embedded APIkit Console?

[implicit]

Implicit

Yes

[client_credentials]

Client Credentials

No

[password]

Resource Owner Password Credentials

No

[authorization_code]

Authorization Code

Yes

Applying the OAuth 2.0 Token Validation Policy

To apply the OAuth 2.0 Access Token Enforcement Using External Provider policy to an API, use the procedure for applying policies described earlier. Configure the optional scopes and required token validation endpoint URL as follows:

  • Scopes

    In the optional Scopes field, you can enter a space-separated list of supported OAuth scopes, such as read write. Specify scopes that match one or more of the scopes defined on the referenced OAuth 2.0 Provider application. If the OAuth 2.0 Provider application defines no scopes, leave this field blank. If you plan to use API Console to simulate the API, leave scopes blank and apply the CORS policy.

  • Access Token Validation Endpoint URL

    In the required Access Token validation endpoint url field, you must enter the URL of the external OAuth 2.0 Provider used for granting the access token, for example https://oauth2provider.cloudhub.io/validate.

    external-oauth-2.0-token-validation-policy-ba3c0

Obtaining API User Information

In some cases, you might want to get information about externally authenticated users who use your API. Place the following script between the inbound and outbound endpoints of the proxy application to which you applied the policy. The script executes after the enforcement of the policy:


         
      
1
2
3
<expression-component>
    message.outboundProperties.put('X-Authenticated-userid', _muleEvent.session.securityContext.authentication.principal.username)
</expression-component>

This script stores the user name in the mule message as an outbound-property named X-Authenticated-userid. The HTTP Connector, used to generate the proxy’s output, transforms any outbound properties that reach it into HTTP message headers. In this way the message that reaches the API after passing through your proxy includes an HTTP header named X-Authenticated-userid, containing the user name.

You can modify this code to change the name of the header being created.