OAuth 2 Policy – MuleSoft API Manager

In this blog post I will be showing how to use MuleSoft API Manager to protect an API with OAuth 2 authentication. OAuth 2 delegates user authentication to service(such as FaceBook, Twitter, GitHub etc) that hosts the user account, and authorizes external applications to access the user account. Inorder to use OAuth2, we will need OAuth 2 provider. There are a lot of OAuth2 providers already existing in the market or you can also create a custom OAuth 2 provider. For the scope of this post, I will be using GitHub as OAuth 2 provider.  Below is high level interaction of the flow I will be walking through.

Client Application: Postman will be used as the client application which will be requesting for OAuth 2 access token from GitHub. The token retrieved will be used to invoke the Mule API.

Authorization Server: GitHub will be used as the Authorization server which will authorize the client and send the OAuth 2 token back to the client

Resource Server and Token Validation: GitHub will be used as Resource server. Although client application is not directly invoking the resource, API Gateway is configured to invoke a resource on GitHub with the access token. If invocation of resource fails, API Gateway returns back error response to the client application. If the invocation result was successful, API Gateway will call the actual API and returns the API result. The reason I am calling resource here is just to validate the token, by invoking the resource, API Gateway is getting the token validated. Ideally, you will have a token validation url to validate OAuth 2 token. Since GitHub doesn’t have a separate token validation url, I am invoking the resource which will validate the token and serve the purpose of this example.

Inorder to use GitHub as oauth provider, we need to create a OAuth 2 app inside GitHub.

If you prefer video version of this post, it can be found on YouTube

Configuring GitHub for OAuth2

1. Login to GitHub and go to Developer settings ( Click on profile pic –> settings –> Developer Settings)
2. Click on New OAuth app and create new application In the authorization callback URL I am using Postman callback as I will be invoking this via postman
3. Once the app is configured, you will be able see Client Id and Client Secret which will be used in Postman(or client application) to get the OAuth token

Now that we have GitHub configured to accept OAuth2 and also have Client Id and Client Secret, the next step is to configure API Manager

Configuring API Manager for OAuth2 policy

Login to API Manager and select the API on which the policy needs to be applied. Under policies, click on “Apply New Policy” and select OAuth 2 policy as shown below

While configuring the policy, enter validation token endpoint url in the policy as: https://api.github.com/user. As explained before, since github doesn’t have a standalone token validation url, we will be using a resource url to indirectly validate the token.

Once the policy is applied, if you try to access the api without OAuth 2 token in either header/url parameter, api manager will return error about missing token.

Invoking API with OAuth 2 token

In this example, I am using postman as the client application to access API which is protected by the OAuth 2 policy. We can request for OAuth 2 token in Postman by selecting OAuth2 Type in the header tab and specifying the required details(as shown in the screen shot) to get new access token.

The Client ID and Client Secret in the above screen shot can be copied from the OAuth app created in GitHub. For Scopes, below is the list of scopes supported by GitHub

• blank(no scope specified) – public read-only access (includes user profile info, public repo info, and gists).
• user – DB read/write access to profile info only.
• public_repo – DB read/write access, and Git read access to public repos.
• repo – DB read/write access, and Git read access to public and private repos.
• gist – write access to gists

Reference Link: https://gist.github.com/technoweenie/419219

Once you click on Request Token, user will be required to authenticate via GitHub login.

After successful authentication, a token will be generated which can be used as either Header or Url parameter while calling the MuleSoft API

This is a quick/simplest way to add OAuth 2 protection on top of an existing policy using MuleSoft API Manager and GitHub without changing the API itself.

Referenced Links:

Authorizing apps on GitHub

GitHub OAuth Busy Developer’s Guide

Introduction to OAuth2

Detailed walk through of this post can be found at YouTube