Nav

Building an OAuth2 Provider

This document covers how to build an OAuth2 provider using API Gateway 2.0 or later. API Gateway 2.x uses the HTTP connector, whereas earlier runtimes use the deprecated endpoint-based HTTP transport, which is not suitable for use with the provider. On earlier versions of API Gateway runtime, you can apply the OAuth 2.0 Provider and OAuth Token Enforcement Policies.

To build a provider to run on Mule 3.7.x, use the following software:

  • Anypoint Studio 5.x with API Gateway runtime 2.x or later

  • Java JDK 1.7 or later

To build a provider to run on API Gateway runtime 2.x, download one of the following OAuth2 provider templates:

Download the keystore.jks that is required for configuring the OAuth2 Provider.

Configuration Overview

To build the OAuth provider application on API Gateway runtime 2.x:

  1. Import the downloaded OAuth2 provider template .zip file into Anypoint Studio as an Anypoint Studio Generated Deployable Archive (.zip), selecting the API Gateway 2.x Runtime.

  2. Specify the client Id and client secret of the organization you use to the API is managed.

  3. Copy the downloaded keystore.jks file to src/main/resources.

  4. Set the following properties in src/main/resources/mule.dev.properties.

    For single authentication:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    
    # Properties to use in a development environment
    key.store.password=mule123
    key.store.key.password=mule123
    key.store.path=keystore.jks
    admin.name=name
    admin.password=password
    validate.endpoint.path=validate
    authorization.endpoint.path=authorize
    access.token.endpoint.path=access_token
    scopes=
    supported.grant.types=AUTHORIZATION_CODE RESOURCE_OWNER_PASSWORD_CREDENTIALS CLIENT_CREDENTIALS IMPLICIT

    For LDAP authentication:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    
    # Properties to use in a development environment
    key.store.password=mule123
    key.store.key.password=mule123
    key.store.path=keystore.jks
     
    ldap.userDn=cn=Manager,dc=my-domain,dc=com
    ldap.password=root
    ldap.url=ldap://localhost:389/dc=my-domain,dc=com
    ldap.search.filter.1=ou=people,dc=my-domain,dc=com
    ldap.search.filter.2=(uid={0})
    validate.endpoint.path=validate
    authorization.endpoint.path=authorize
    access.token.endpoint.path=access_token
    scopes=
    supported.grant.types=AUTHORIZATION_CODE RESOURCE_OWNER_PASSWORD_CREDENTIALS CLIENT_CREDENTIALS IMPLICIT
  5. If you plan on deploying the OAuth 2 provider to the same server as the API, change the port where it’s hosted to avoid conflicts. In src/main/resources, in common.properties, change the http.port property to anything other than 8082, for example 8083.

  6. Open the config.xml file in Studio.

  7. On the Global Elements tab, under the canvas, edit the OAuth Provider module to remove the default READ WRITE from Scopes:

    1. In Configuration XML, accept defaultScopes="" and scopes=""

    2. In userValidation.xml: within validateTokenFlow, specify scopes="" in the oauth2-provider:validate element.

End-to-End Example Implementation

In this example of how to build the OAuth Provider application, you configure API Gateway runtime 2.x or later to use the same client Id and client Secret as the organization where the API is managed.

You need to configure HTTPS and deploy the proxy as described in Using HTTPS and shown in the example implementation of the provider.

  1. Download API Gateway 2.0 version or later and configure the runtime.

  2. Copy the downloaded keystore file to the /conf directory of the API Gateway installation.

    1. Log into Anypoint platform and get the client_ID and client_secret of your organization or of one of its Business Groups.

    2. Edit the /conf/wrapper.conf file from the API Gateway software distribution to add the client ID and client secret.

      The numbers in the prefix wrapper.java.additional. n of these parameters must run sequentially in order starting with 1 on the top parameter in the file, as shown in the following example.

      
                     
                  
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      
      ...
      
      wrapper.java.additional.13=-XX:MaxNewSize=512m
      wrapper.java.additional.14=-XX:MaxTenuringThreshold=8
      
      ...
      
      ######################################################################################
      # Anypoint Platform 2.0 Settings
      ######################################################################################
      # The following option is mandatory and identifies your Mule instance against
      # the Anypoint Platform.
      #
      #wrapper.java.additional.<15>=-Danypoint.platform.client_id=XXXXXXXX
      #wrapper.java.additional.<16>=-Danypoint.platform.client_secret=XXXXXXXX
      #
      ...
    3. Edit the api-gateway domain to support HTTPS, which supports only HTTP by default, and to point to the keystore. This domain is used by the proxies you deploy to the API Gateway, and allows for multiple proxies to share a single port. Also provide HTTPS credentials .

      Open the file mule-domain-config.xml in the folder /domains/api-gateway of the API Gateway directory. Uncomment the second http:listener-config element and then fill in the fields relative to the keystore. Use the provided keystore.

      
                     
                  
      1
      2
      3
      4
      5
      
      <http:listener-config name="https-lc-0.0.0.0-8082" host="0.0.0.0" port="8082" protocol="HTTPS">
              <tls:context name="tls-context-config">
                  <tls:key-store path="${mule.home}/conf/keystore.jks" password="mule123" keyPassword="mule123"/>
              </tls:context>
      </http:listener-config>
  3. Deploy the API and apply the OAuth 2.0 Access Token Enforcement Using External Provider policy.

  4. Start API Gateway Runtime.

  5. Copy /examples/apps/leagues-rest to the /apps folder within your gateway installation.

    You can open the Leagues app by browsing to http://localhost:8080/api/teams resource, look at the RAML file, and use API Console to simulate calling the app.

  6. Log into Anypoint platform.

  7. Register an API in Anypoint platform named External AES Tutorial and version 1.0.

    You can use this RAML file as a reference:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    
    #%RAML 0.8
    title: External AES Tutorial
    version: 1.0
    baseUri: http://localhost:8080/api
    /teams:
      displayName: Teams
      get:
        queryParameters:
          city:
            type: string
            required: false
            example: Barcelona
        responses:
          200:
            body:
              application/json:
                example: |
                  [{
                    "name": "Athletic Bilbao",
                    "id": "ATH",
                    "homeCity": "Bilbao",
                    "stadium": "San Mames"
                  },
                  {
                    "name": "Atletico Madrid",
                    "id": "ATL",
                    "homeCity": "Madrid",
                    "stadium": "Vicente Calderon"
                  }]
  8. Save the API, return to the API administration page, and click the API name to view API Definition, Portal, and Status page. 

  9. Click API Status > Configure endpoint to create an HTTPS API proxy. Fill in the required information using HTTPS to match the previous configuration of the gateway. 

  10. Click Save.

  11. Download the proxy. Select Download proxy (for latest gateway version).

  12. Test that the proxy application is running at https://localhost:8082/leagues/teams

Applying the External OAuth2 Policy to the API

You can include RAML snippets in your API from the API Manager Available Policies list to enforce policies.

  1. In the API version details page, on the Policies tab, click the RAML Snippet link for the OAuth 2.0 Access Token Enforcement Using External Provider policy, and add the RAML snippet to the RAML code of the API in Designer.

  2. Select "OAuth 2.0" from a dropdown menu in the application console.

  3. Open the API version page of the API, and on the policies tab, apply OAuth 2.0 Access Token Enforcement Using External Provider policy, providing the validation URL, for example:  https://localhost:8083/validate

    If you are going to use API Console, do not specify any scopes parameters, but do apply the CORS policy.

  4. Open the https://localhost:8082/console and try to get the teams resource.

    A 403 status code returns because no OAuth credentials were present in your request.

Testing the External OAuth2 Policy

In the previous section, you verified that the policy correctly rejects requests that don’t provide credentials. Now, verify that a request that includes credentials succeeds.

  1. Obtain OAuth credentials:

    1. If your API doesn’t have a portal, create a portal, make it public, and register an application to access the API. During the registration, leave Redirect URI empty. + On the API version details page, on the Application tab the registered application appears.

  2. Get the client ID and secret for the registered application.

  3. Open https://localhost:8082/console.

  4. Through the API Console UI, try to send a request the teams resource. Fill in the fields with the following:

    1. Security Scheme →  OAuth2

    2. Authorization Grant → Implicit

    3. Client ID → Use the credentials of the registered application:

      ext-oauth2-client-id

  5. Click GET, and you are prompted for the user name and password that you set up in the configuration OAuth 2.0 external provider application (in this example, username: name password: password )

    ext-oauth2-ping-api

  6. Login and Authorize.

    A 200 status code and response appears.

    ext-oauth2-login-and-auth