HowTo – Apply an OAuth policy on a REST API

Pre-requisites:

• Anypoint Platform – MuleSoft Anypoint Studio
• Anypoint API Gateway – On Prem
  We can deploy the application to Cloudhub. But for this tutorial, we are using the on-premise runtime. If you require cloud runtime, please refer to this link.
• Sign up for an Anypoint Account
• Postman to test the API call in case of testing REST API

Steps:

1. We will obtain the client id and client secret for the Anypoint account so we can use it to configure the on-premise API gateway runtime. Click on the settings icon. 
   Click on the Organization name that was used during the account signup. 
   This will bring up a dialog box that gives the client id and client secret for the Anypoint account. We will configure the on prem API gateway with these parameters so we can manage the APIs and visualize analytics from Anypoint platform for APIs running in the cloud.
2. Download the on-premise API gateway runtime and refer to this link to configure it. After following the configuration, we can run it by giving the client id and secret we noted earlier for the platform account. We will also give the environment name as an argument. Following is an example. 
3. In this tutorial, we are going to apply an OAuth policy to an API. There can be the following scenarios:
   • Existing SOAP or REST service – In this case please follow this link to create a proxy to the back-end web service. Download and deploy the proxy application to gateway runtime
   • Create a REST API using mule Anypoint platform – We walked through this use case in part 2 of this series. Deploy this application to the gateway runtime.
4. Assuming we pick one of the above two scenarios, when we login to our Anypoint Platform account we can view the API application we registered. Using the example from part 2 we can see the application name “rest-api-howto” registered on the platform.
   
5. Click on the entry and we will see the API detail page. Here we can see the API status is marked as green which says that we can actively manage the API. So we will click on the “Policy” tab to see all out of the box policies that are available.
   
6. Now before we apply the OAuth policy we can have the following two scenarios.
   • Use an external OAuth provider: Make a note of the OAuth URLs for validation, authorization and access token provided by the external OAuth provider. Go directly to step 7
   • Use Mule to host an OAuth provider

   

   latest report

   Learn why we are the Leaders in API management and iPaaS

   Read reports

   In the case of using Mule to host an OAuth provider, log into Anypoint Exchange. Search for OAuth provider in search and you will see two entries show up. Click on the details for “External OAuth 2.0 server for Anypoint Platform“.
   Click on “View step-by-step tutorial” and follow the instructions for section 2 of the tutorial to configure the properties.
   After configuring the properties, make a note of the OAuth URLs for validation, authorization, and access token.
   

7. Go back to the API detail page on Anypoint Platform for API management. On the “Policy” tab scroll down to find policy name “OAuth 2.0 access token enforcement using external provider”. Click Apply. This will pop up a dialog. Enter the OAuth validation URL in the box labeled “Access Token validation endpoint URL”. Click Apply. This will activate the OAuth policy on our API.
   
8. Before we test our API we need to define a client application with which we will request access to the API. This is done via the developer portal for the API. Go to API detail page and on the central panel click on the drop down and pick “Create new portal”.
   
9. This will bring up the portal template. We can add styling and documentation to the portal. For now, we will use it as is and click on the “Public view” to bring up the developer portal public view.
   
10. Click on the top right button “Request API access”.
11. This will bring up a dialog where we can either pick an existing application or create a new client application. Click on “Request API access” after creating a new application.
    
12. By default, the client application is auto-authorized and granted access. A client id and client secret is assigned to the client application. We can get this information from the developer portal view list of client applications. Note the id and secret.
13. Bring up Postman to test our API. Enter the API URL with the relevant query param and method. When we click on “Send,” we will get an error message saying “Missing access token”. This is because our API is protected with OAuth policy and requires relevant OAuth parameters in the request.
    
14. Refer to this link to see how Postman can be used to request for OAuth access token. Fill in the relevant OAuth URLs in postman.
    
15. Once we obtain the access token and click “Send” we get the response message populated with data.
    

Quick recap:

1. An API needs to be protected with an OAuth policy.
2. The policy can be added via Anypoint API management console.
3. An OAuth provider can be external or hosted in Mule. The OAuth provider can be downloaded from Anypoint Exchange.

An API lifecycle is an iterative process of requirement gathering, design, and validation. Once validated, it is built, governed and shared with the community. Mulesoft’s Anypoint Platform offers a unified platform to achieve this entire process with a single console to manage.