Tutorial: Implementing OAuth Security

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

About this tutorial

In this tutorial you will complete the following lessons:
  1. Create a Native OAuth Provider
  2. Adding OAuth Security to an API
  3. Test OAuth Security

Before you begin

In this tutorial you will implement and test OAuth security. To complete this tutorial, you must have the following available:
  1. An existing published API. If you do not have an API available, complete the Tutorial: Importing an API tutorial.
  2. An existing client application. If you do not have a client application available, complete Tutorial: Creating a Client Application.
  3. An external application, such as cURL, used to send requests to the OAuth token provider endpoint.
Note: The Sandbox catalog must be configured to use either a DataPower® Gateway (v5 compatible) or a DataPower API Gateway or both. See Creating and configuring Catalogs.

Create a Native OAuth Provider

To create a native OAuth provider by using API Manager, complete the following steps:
  1. Log in to API Manager.
  2. Click the Resources icon Resources icon in the side bar.

    APIM screen

  3. On the User Registries page, click Create.

    User registries page

  4. Click Authentication URL User Registry.

    Registry types

  5. Take the following steps:
    1. Enter AuthURL in the Title and Display Name fields.
    2. Enter https://httpbin.org/basic-auth/user/pass in the URL field.
    3. Select No TLS client profile in the TLS Client Profile field.
  6. Click Save.

    Auth URL Registry

  7. Click Save.
  8. Click OAuth Providers.

    User Registry list

  9. Click Add > Native OAuth provider.

    Add new OAuth Provider

  10. Enter MainProviderOA in the Title field.
  11. In the Gateway Type section, select the gateway type in use by the catalog. This defaults to DataPower Gateway (v5 compatible). You may need to change this selection.
    Note: The gateway type selected here must match the gateway type used by the API that uses this provider.
    Click Next.

    New provider form

  12. Select Resource owner - Password in the Supported grant types field. Deselect any others if necessary.

    New provider form

  13. Click Next.
  14. In the Scopes section, enter details in the first NAME field. Enter Branch details in the first DESCRIPTION field.

    New provider form

  15. Click Next.
  16. Under Authentication, select the AuthURL Authentication method.

    New provider form

  17. Do not alter the default Authorization setting (Any Authenticated). Click Next.

    New provider form

  18. A Summary page appears. Scroll down and click Finish.

    New provider form

  19. The Info page appears. Scroll down and select Enable debug response headers. Click Save.

    New provider form

  20. Click the Manage icon The Manage icon in the side bar.

    Edit provider form

  21. Click the Sandbox catalog icon.

    Sandbox test app credentials

  22. Click the Settings icon The Settings icon in the side bar.

    Sandbox product list

  23. Click API User Registries.
  24. Click Edit.

    API reg list

  25. Select AuthURL. Click Save.
  26. Click OAuth Providers.

    API reg list

  27. Click Edit.

    OAuth provider list

  28. Select MainProviderOA. Click Save.
  29. Click API Endpoints .

    OAuth provider list

  30. Make a note of the gateway URL. You will need this to obtain an OAuth token.

    API endpoints

Verify or create test application credentials

You will need the client ID and client secret for an application to test the OAuth functionality. You obtained this information during the completion of the Tutorial: Creating a Client Application tutorial listed in the Prerequisites.
Note: These steps are necessary only if you did not make note of the credentials for the client application you previously created.
  1. Click the Applications icon Applications icon in the side bar.
  2. Click the Down arrow icon alongside the AppOne application. The findbranch product should be listed.

    Applications page

  3. Click the Options icon Options icon alongside AppOne. Select Credentials.

    App options

  4. Click Add.

    App credentials

  5. Copy both the Client ID and client Secret. You will need these values to obtain an OAuth token. Click Create.

    New credentials page

  6. Click the Back arrow until you see the Manage page.

    Credentials list

  7. Click Develop Develop icon in the side bar.

    Manage page

Adding OAuth Security to an API

You add OAuth security enforcement to an existing API by creating a security definition for OAuth and then including that definition in the security applied to the API. Follow these steps.
  1. Click the existing API to which you want to add OAuth security. This tutorial uses the FindBranch API.
    Note: The gateway type used by this API must match the gateway type used by the OAuth Provider you just created. The gateway type for the API is shown at the foot of the API Setup page.

    API list

  2. Click Security Definitions.
  3. Click Add.

    Security definitions

  4. Enter ProviderOA in the Name field.
  5. Under Type, click OAuth2.
  6. Select MainProviderOA in the OAuth Provider field.
  7. Select Resource owner in the Flow field.
  8. Click Save.

    New OAuth security

  9. Click Security.

    Security definitions

  10. Under Security Definitions, select ProviderOA, and select details.

    New security

  11. Click Save.

Test OAuth Security

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 the new OAuth security added to the API, complete the following steps:
  1. Click Assemble.
  2. Click the Test icon The Test icon.

    Assemble page

  3. On the test Setup pane, click Republish product.

    Test setup

  4. You must now resubscribe the test application to the test product. Right-click the Manage icon The Manage icon, and select Open Link in New Tab.

    Test setup

    Take the following steps to navigate to the catalog applications page.
    1. Log in to the Manager page again.
    2. On the home page, click Manage.
    3. Click Sandbox to open the catalog.
    4. Click Applications to open the list of available applications.

      Applications

    5. Click the Options icon Options icon alongside the AppOne application. Select Create Subscription .

      Applications

    6. Select FindBranch. Click Create .

      Applications

    You must now return to testing the republished API. Close the currently open browser tab to return to testing the API you just republished.

  5. Select get /details in the Operation field.

    Test setup

  6. Enter the client ID you created previously in the clientId field.
  7. Enter the client secret you created previously in the clientSecret field.

    Input client credentials

  8. Enter user in the Username field. Enter pass in the Password field.

    Input client username

  9. Obtain an OAuth token. In this case, cURL is used to obtain the token using the following command.

    curl -k https://gateway_url/org_name/sandbox/mainprovideroa/oauth2/token -d "grant_type=password&scope=details&username=user&password=pass&client_id=app_client_id&client_secret=app_client_secret"

    Obtaining a token

  10. Enter or paste the access token in the explorer_access_token field. Here is an example token.

    AAIgMzU4MjRmMjY0NmY3OTllZjRjM2Y3OWU1ZDQwZGYwYWOxkwNYTnIxWaHu8Htf1OUAQUEGl3TLJVHayXjPJE5Rxd7clNdBEYRAEkuHIWX8hR2KF4AA9_SuOCNxJsETDaiJ

    Input OAuth token

  11. Click Invoke. You may encounter a yellow error box with a URL embedded in it. Click this URL to override a browser certificate error.

    Test invoke

  12. Click Invoke again. The response contains branch data.

    Repeat invoke

What you did in this tutorial

In this tutorial, you completed the following activities:
  • Created an OAuth Provider.
  • Made the OAuth provider available within the catalog.
  • Added OAuth security to an existing API.
  • Tested the OAuth security.