In this tutorial, we will demonstrate step by step guide to implement OAuth 2.0 using Mule OAuth 2.0 Provider in Mule 4.

What is OAuth 2.0?

OAuth 2.0 is secure protocol that allows a user to grant third-party web site or applications to access user’s protected resource without revealing the underlying credentials.

Who is OAuth Providers?

It is a software which provides the secure token to the client and validates the token. There are many third party OAuth providers like Auth0, Okta, Git, Salesforce, etc.,

Fortunately MuleSoft also have its own OAuth provider – We are going to discuss more about it with example.

Read this Auth0 official documentation to understand more about OAuth 2.0 framework.

What is Mule OAuth 2.0 Provider?

Mule OAuth 2.0 Provider is an OAuth 2.0 provider alternative developed by MuleSoft that can be used in any MuleSoft API Platform organization, including the federated ones.

The modules available in Mule OAuth 2.0 provider are:

1. CREATE CLIENT
2. DELETE CLIENT
3. VALIDATE TOKEN
4. REVOKE TOKEN

Implementing Mule OAuth 2.0 Provider

Before get started, you must meet the below requirements:

Follow below steps to implement the Mule OAuth 2.0 provider in Mule 4.

Step 1: Create a Mule project and name it as mule-oauth-provider.

Step 2: Create two global Object Store configurations to store Clients credentials and access tokens.

Create another Object Store and change the name to token_object_store.

Step 3: Create global OAuth 2.0 provider configurations as follows

Provider name: Mule_OAuth_Provider
Listener config: Create new HTTP Listener configuration.
Client validation rate limiter: Leave the default settings.
Client store: Refer the client_object_store
Supported gran types: CLIENT_CREDENTIALS
Token config: Edit inline
   Path: /token
   Token store: Refer the token_object_store

Leave the other default settings as is.

Token config:

CREATE CLIENT:

Step 1: Add HTTP Listener and refer the exiting listener configuration.

Step 2: Add Create Client operation and configure as follows

Other empty fields are optional and you can configure as per your business needs.

Step 3: Add transform message and set some response message such as Client has been created.

The create-client flow would look like:

GET CLIENT:

There is no such operation in OAuth 2.0 provider module and its a inbuilt process. Do you remember that we have already configured the Token configuration in OAuth provider module.

VALIDATE TOKEN:

Step 1: Create a new flow with HTTP Listener configure as follows

Step 1: Add Validate Token operation and configure as follows

The Access token script is auto populated by default. Its simply splitting the message and accessing the second part.

We will pass the access token in the authorization header as follows.

For examle,

Your Mule flow would look like

That’s it! Now we have developed the Mule OAuth provider with following endpoints.

Create Client : http://<<host:port>>/createClient
Get Token: http://<<host:port>>/token
Validate Token: http://<<host:port>>/validate

Now deploy the Mule OAuth provider application.

Applying OAuth 2.0 Policy

Now let’s apply the Mule OAuth 2.0 policy to the API that we deployed earlier (not the above developed application).

Step 1: Update your API Specification with below code (securitySchemes and securedBy) and publish API Spec.

Sample API Specification:

#%RAML 1.0
title: Employees Exp API

securitySchemes:
  oauth_2_0:
    description: |
      This API supports OAuth 2.0 for authenticating all API requests.
    type: OAuth 2.0
    describedBy:
      headers:
        authorization:
          description: |
             Used to send a valid OAuth 2 access token. Do not use with the "access_token" query
             string parameter.
          type: string
      queryParameters:
        access_token:
          description: |
             Used to send a valid OAuth 2 access token. Do not use together with the "Authorization"
             header
          type: string
      responses:
        400:
          description: Invalid token.
        401:
          description: |
            Unauthorized or Connection error when connecting to the authorization server.
        403:
          description: |
            Forbidden, invalid client application credentials.
        500:
          description: |
            Bad response from authorization server, or WSDL SOAP Fault error.

/employees:
  get:
    securedBy:
      - oauth_2_0
    responses:
      200:
        body:
          application/json:
            example: !include /examples/listEmployees.json
              

Step 2: Go to API Manager and open the API you want to secure. In our case, Employees Exp API and update the Asset Version to latest version.

Step 3: Click on Policies, Apply New Policy and search for OAuth 2.0 access token enforcement using Mule OAuth provider.

Step 4: Select latest version and click on Configure Policy.

Step 4: Leave all default values as is and provide your OAuth provider validate endpoint.

You can get the host name from the Runtime manager.

Testing Mule OAuth 2.0 Provider

Now let’s see how our Mule OAuth 2.0 will secure our Mule API’s.

Step 1: First we will need to create client. This step is performed by developers. Its like registering Client application.

Step 2: Get an access token by providing the client_id, client_secret and the grant type as follows,

Step 3:

Scenarios#1: Access API without passing the access token.

Scenario#2: Access API with invalid access token.

Scenario#3: Access API with valid access token.

In simple steps,

1. Create a client using Create client operation.
2. Retrieve access token using /token endpoint as we don’t have separate operation.
3. Pass the access token in headers (Authorization) or in query parameters (access_token) depends on your security schemes snippet configuration.

Points To Remember

We hope this article helped you to understand and implement the Mule OAuth 2.0 provider to secure Mule API’s using OAuth 2.0 policy.

If you face any issues while implementing the Mule OAuth 2.0 provider, please do let us know in the comment section.

Please do share it with your friends and don’t forget to follow us on Facebook, Twitter and LinkedIn. Visit our MuleSoft Hub for more tutorials and updates.