HowTo – Apply an OAuth policy on a REST API

In the previous post in the “APIfy your integrations” series, we went through an API design-first approach to building integrations to back-end systems.
We defined the API specification using RAML, implemented the API by importing the RAML into Anypoint Studio and deployed the implementation to mule runtime in cloud or on-premise.
We are now ready to share the API with the developer community. Before sharing, we need to make sure that the API is governed. Governing an API means applying policies like rate limiting, SLA based tiering and securing API access with industry standard protocols.
One popular way to secure APIs is OAuth (Open Authorization). OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for Web applications, desktop applications, mobile apps and Internet of Things. Here’s more about how OAuth 2.0 works.
Mulesoft’s Anypoint Platform provides a policy template to implement OAuth out of the box. In this post, we will go through the step-by-step process of configuring the OAuth policy to enforce OAuth on an API.

Pre-requisites:

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. Anypoint_Platform
    Click on the Organization name that was used during the account signup. Fullscreen_11_27_15__5_01_PM
    This will bring up a dialog box that gives the client id and client secret for the Anypoint account. Fullscreen_11_27_15__5_02_PMWe 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. bin_—_bash_—_202×55_and_javascripting_—_bash_—_202×57
  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.
    Anypoint_Platform_for_APIs___API_administration
  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.
    Anypoint_Platform_for_APIs___API_administration___rest-api-howto-api_-_1_0_0
  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

    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.
    Exchange

  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.
    Anypoint_Platform_for_APIs___API_administration___rest-api-howto-api_-_1_0_0
  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”.
    Fullscreen_11_27_15__12_03_AM
  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.
    Fullscreen_11_27_15__12_03_AM
  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.
    Fullscreen_11_27_15__12_04_AM
  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.
    Postman
  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.
    Postman
  15. Once we obtain the access token and click “Send” we get the response message populated with data.
    Postman_and_raml_snippet_oauth_-_Google_Search

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.


We'd love to hear your opinion on this post


3 Responses to “HowTo – Apply an OAuth policy on a REST API”

  1. I am not able to test my api from postman.
    I am getting error “Resource not found”
    What to do

    Agree(0)Disagree(0)Comment
    • Hi Mallick,
      Can you test the project without applying the OAuth policy ?
      Regards,
      Neerav

      Agree(0)Disagree(0)Comment
      • This is great stuff, but I noticed it only worked for me if I also put in the property file(mule.dev.properties) the below line with the grant types that are allowed:
        supported.grant.types=AUTHORIZATION_CODE RESOURCE_OWNER_PASSWORD_CREDENTIALS CLIENT_CREDENTIALS IMPLICIT

        Agree(0)Disagree(0)Comment