Tutorial: Implementing OAuth Security

This tutorial shows you how to create a native OAuth provider using the API Manager user interface.

About this tutorial

Creating a native OAuth provider lets API Connect perform OAuth authorization tasks internally instead of requiring a third-party application to complete them. When you create a native OAuth Provider, you apply it to an API, which is then updated to include the OAuth configuration. Then you publish the API. Whenever the published API is invoked, API Connect ensures that the calling application is authorized to access the API resources, and then makes the API available.

Implementing OAuth security requires you to create a provider, and then update your API to use the provider. In this tutorial you will complete the following lessons:

Create a native OAuth provider
Add OAuth security to an API
Add an OAuth redirect URL to the default Sandbox test application
Test the OAuth security implementation

Before you begin

This tutorial uses the predefined FindBranch API. To prepare your environment for this tutorial, complete the following tasks:

Add the DataPower® API Gateway service to the Sandbox catalog as explained in Creating and configuring catalogs.
The Sandbox catalog must be configured to use at least one gateway. For this tutorial, you must use the same gateway that the FindBranch API uses.
Import the FindBranch API and activate it as explained in the tutorial, Tutorial: Importing an API.

Create a native OAuth provider

To create a native OAuth provider in API Manager, set up a user registry that uses an external authentication URL to verify users, and then create a provider to authenticate users who log in with that registry.

Create a user registry that can be used for authenticating users with OAuth:
1. Log in to API Manager.
2. On the Home page, click the Manage resources tile.
3. On the Resources page, in the left pane, select User registries.
4. In the User registries section, click Create.
5. On the Create user registry page, select the Authentication URL user registry tile. On the Create User Registry page, click Authentication URL User Registry as the selected user registry type.
6. On the Create authentication URL user registry page, enter the following information.
  1. In the Title and Display Name fields, enter AuthURL.
    By entering AuthURL in the Title and Display Name fields, you can easily determine that this registry is configured with an authentication URL.
  2. In the URL field, enter https://httpbin.org/basic-auth/user/password.
    Note: The URL provided here is for testing purposes only. The httpbin.org endpoint provides a sandbox where you can simulate a login with basic authentication by passing credentials in the authorization header that match the {user} and {password} path parameters.
  3. From the TLS client profile (optional) drop down list, select No TLS profile.
  4. Click Save.
    
    The Resources page displays with the new registry included in the list.
To create an OAuth provider to authenticate users who log in with the AuthURL registry, perform the following tasks.
1. In the navigation list of the Resources page, click OAuth providers.
2. In the OAuth providers section, click Add > Native OAuth provider.
  
  The Create Native OAuth Provider page is displayed.
3. Under the Native OAuth provider section, enter the following information.
  1. In the Title field, enter MyNativeOAuthProvider.
  2. Under the Gateway type section, select the DataPower API Gateway radio button (the same gateway used by the FindBranch API).
    Note: Each native OAuth provider applies to one gateway type. The gateway type that you select here must match the gateway type used by the API that will be secured with this new provider.
  3. Click Next.
4. Under the Supported grant types section, perform the following tasks.
  1. Select the Access code check box and deselect all the other grant types.
    Note that, this tutorial uses a single grant type to illustrate how the native OAuth provider functions.
  2. Click Next.
5. Under the Scopes section, perform the following tasks.
  1. Click to delete the default scope.
  2. Click Add to define the scope of the API that will be secured by the native OAuth provider.
  3. In the Name field, enter details.
  4. In the Description field, enter Branch details
  5. Click Next.
6. Under the Authorization Endpoint section, perform the following tasks.
  1. Under the Authentication section, from the Authenticate application users using drop down list, select AuthURL.
  2. Click Next.
7. Under the Native OAuth provider summary section, review the settings and then click Finish.
  Once the new provider is saved, their information becomes available for editing and is displayed on the Info page.
8. On the Info page, perform the following tasks.
  1. Select the Enable debug response headers checkbox.
    Selecting this checkbox includes error details in the response headers when issues occur.
  2. Click Save.
  The new native OAuth provider is now complete.
To configure the AuthURL registry so that it functions as an API user registry in the Sandbox catalog, perform the following tasks.
1. In the navigation pane, click the Manage icon .
2. On the Manage page, click the Sandbox catalog tile.
  
  The Products page is displayed.
3. On the Menu bar, select Catalog settings.
4. In the left pane, click API user registries.
5. In the Add API user registries section, click Edit.
6. On the Edit API user registries page, perform the following tasks.
  1. Select the AuthURL check box.
  2. Click Save.
    
    The new registry displays in the list of API user registries as depicted in the following image.
To configure your native OAuth provider and make it available in the API Manager interface, perform the following tasks.
1. Select Manage > Sandbox > Catalog settings.
2. In the left pane, click OAuth providers.
3. In the OAuth Providers section, click Edit.
4. On the Edit OAuth provider page, perform the following task.
  1. Select the MyNativeOAuthProvider checkbox.
  2. Click Save.
  MyNativeOAuthProvider displays in the list of providers that are configured that you can use with API Manager.

Add OAuth security to an API

Create a security definition for the FindBranch API and include your native OAuth provider information.

Go to the API Manager Home page.
On the Home page, click the Develop icon.
Alternatively, select the Develop APIs and products tile.
On the Develop page, Under APIs, select the API that you want to modify. For example, FindBranch.
On the FindBranch API's Design page, perform the following tasks.
1. In the left navigation pane, select Security Schemes.
2. Under the Security Schemes section, click Add.
3. In the Add schema pop up window, perform the following tasks.
  1. In the Security Definition Name (Key) field, enter FindBranchOA.
  2. From the Type drop down list, select oauth2.
  3. From the OAuth Provider (Name) (optional) drop down list, select MyNativeOAuthProvider.
  4. From the Flow drop down list, select Access Code.
  5. Retain the pre-filled values in the Authorization Url and the Token Url fields.
  6. Click Add.
    
    FindBranchOA is now displayed under Security Schemes.
  7. In the right pane, under the FindBranchOA section, click the details link and verify that the scope you defined for the native OAuth provider displays.
  8. On the top right corner of the page, click Save.
4. In the left navigation pane, select Security.
5. In the Security Requirements section, perform the following tasks.
  1. Click Add.
  2. In the Add schema pop up window, select the ClientID and FindBranchOA check boxes and then click Add.
    
    FindBranchOA is now displayed in the Security Requirements section.
  3. Adjacent to FindBranchOA, from the Scopes drop down list, select details.
  4. On the top right corner, click Save.

Adding an OAuth redirect to the Sandbox Test App

To test the OAuth functionality within API Manager, use the Sandbox Test App application. The Sandbox Test App is included with the Sandbox catalog, and is automatically subscribed to the default product for every API that you create within the catalog, so it's always available for testing APIs in API Manager.

Note: Before using the application for OAuth testing, you must update it to include an OAuth redirect URL.

Go to the API Manager Home page.
On the Home, in the navigation pane, click Manage.
On the Manage page, click the Sandbox catalog tile.

The Products page is displayed.
On the menu bar, click Applications.
From the list of applications, select Sandbox Test App application.

The Edit application page is displayed.
On the Edit application page, perform the following tasks.
1. Under the OAuth redirect URLs (optional) section, click the Add redirect URL.
2. In the OAuth redirect URLs (optional) field, enter https://example.com/redirect
  Although this field is optional, you must enter the value for the authorization flow in your OAuth provider. For testing OAuth within API Manager, the URL can be any value that is formatted as a proper URL, but you must use the same value when you provide the redirect URL during testing.
3. After entering the value in the OAuth redirect URLs (optional) field, click the Complete icon to save the value.
4. Click Save to update the application.

Test the OAuth security implementation

Note: Due to Cross-Origin Resource Sharing (CORS) restrictions, the assembly test tool cannot be used with the Chrome or Safari browsers on the macOS Catalina platform.

To test your OAuth implementation, run an API from within API Manager using the Sandbox Test App.

Note: Before running the API,

You must publish the product to ensure that the latest update is online and available for testing.
You must obtain an authorization code and then use it to obtain an access token that allows you to execute the API.

Go to the API Manager Home page.
On the Home page, click the Develop icon.
Alternatively, select the Develop APIs and products tile.
On the Develop page, select the API that you want to test. For example, FindBranch.
On the Menu bar, select Test.
On the Test page, perform the following tasks.
1. Click Authorizations + > Client ID & FindBranchOA.
2. On the Authorize pop up window, perform the following tasks.
  1. Select the Oauth2 tab.
  2. In the Client ID field, enter your client ID.
  3. In the Client Secret field, enter your client secret.
  4. Under Scopes, select the details checkbox.
  5. In the Username field, enter user.
  6. In the Password field, enter password.
  7. Click the Get Token tab.
  8. In the pop up dialog box, enter the API Manager login credentials and then click Sign In or press ENTER.
    
    The Access Token is generated and displayed on the Authorize pop up window.
  9. Under the Access Token section, copy the token.
  10. Click Apply.
On the Menu bar, select Explorer.
On the Explorer page, in the left pane, select GET/details.
In the right pane, under the GET : /details section, perform the following tasks.
1. Select the Try it tab.
2. In the API Secret field, enter your client secret.
3. Under the Authorization section, perform the following tasks.
  1. Select the details checkbox.
  2. In the Redirect URI field, enter https://example.com/redirect.
  3. To obtain the Authorization code, scroll down and click Authorize.
  4. In the pop up dialog box, in the User ID field, enter user, in the Password field, enter password, and then click Sign In or press ENTER.
    
    When you successfully authenticate, your browser redirects to a window that displays the page from the redirect URL. Your authorization code is included in the address bar as a parameter to the URL.
    
    Your authorization code is included in the address bar as a parameter to the URL as displayed the following image. If the URL is https://example.com/redirect?code=AAPl-yX6XVtdROcU4_WJhETLPLjLOJoJIpAYSFf7-4FxcNJ2XfXbMWpu8LnruLtcgmkdjNeDstRi0aO-d8bZX888iQYrtyhfrYSgADZgWy84nw, your Authorization code is, AAPl-yX6XVtdROcU4_WJhETLPLjLOJoJIpAYSFf7-4FxcNJ2XfXbMWpu8LnruLtcgmkdjNeDstRi0aO-d8bZX888iQYrtyhfrYSgADZgWy84nw.
  5. Copy the authorization code from the URL in the window's address bar, capturing everything after "code=".
    For example:
```
https://example.com/redirect?code= AALMmZCyKnhY1HpZGfpHkFH7wDdsNh9R2hgDfGwMVgdEzBOTlnq5LPZ3x6RFPa3V7CzsGacH8LLGlafnqa3ntbh921n5rJE7W0_jC1cAtzcZEg 
```
  6. In the Authorize field, enter the authorization code.
  7. Click Get Token to obtain the access token.
    If the authorization is successful, the Get Token is now filled with the access code.
    
    Tip: If the access token does not appear and you see a message about your authorization code expiring, return to the previous step to request a new Authorization code, and use it to generate the access token.
  8. Click Send.
    The FindBranch API's response displays the Status code 200. You can view the response Headers information, and the Body information that contains each bank branch's data.
    
    You can scroll down and view the information under the Response section.

What you did in this tutorial

In this tutorial, you completed the following activities:

Created a user registry for use with an OAuth provider.
Created a native OAuth provider and made it available within the catalog.
Added OAuth security to an API.
Updated the Sandbox Test App (client application) to provide an OAuth redirect for testing.
Tested the OAuth security by obtaining an authorization code, exchanging it for an access token, and invoking the secured API.