Kubernetes with OpenShift World Tour: Get hands-on experience and build applications fast! Find a workshop!

Secure APIs by using OAuth 2.0

This tutorial shows you how to implement OAuth 2.0 schemes that are available in IBM API Connect to secure an API.

IBM API Connect provides two implementation modes, each of which provide different OAuth 2.0 schemes:

  • Confidential mode. A Confidential mode is suitable when an application is capable of maintaining the secrecy of the client secret. Use confidential mode when an application is capable of maintaining the secrecy of the client secret. This is usually the case when an application runs in a browser and accesses its own server when obtaining OAuth access tokens. As such, these schemes make use of the client secret. In the Confidential mode, we have three OAuth schemes: Application, Password and Access code.

  • Public mode. A Public mode is suitable when an application is incapable of maintaining the secrecy of the client secret. This is usually the case when the application is native on a computer or mobile where the secret would have to be stored on the user’s device, likely inside the source code of the application. As such, these schemes do not make use of the client secret. In the Public mode, we have three OAuth schemes Implicit, Password and Access code.

The OAuth API configuration files for all the OAuth implementation modes and schemes that we will use in this tutorial are available in this GitHub repo.

We will develop the client application by using the Node-RED. The Node-RED flows implement a dummy authentication endpoint and an application endpoint that requires authorization. These Node-RED flows demonstrate how the different OAuth schemes work to authorize access to the application endpoint.

Learning objectives

In this tutorial, you will learn how to:

  1. Configure API Connect for the different OAuth 2.0 schemes.
  2. Develop a Node-RED based client application that uses API Connect to provide authorized access to an endpoint.
  3. Create http requests with headers and payloads for each of the OAuth schemes.

Prerequisites

You’ll need an IBM Cloud Account.

Estimated time

Completing this tutorial should take about 30 minutes.

Steps

  1. Create an API Connect service instance.
  2. Create a Node-RED service instance.
  3. Configure the API Connect service.
  4. Deploy the client application.
  5. Run the application.
1

Create an API Connect service instance

Create an instance of IBM API Connect. Ensure that the Lite plan is selected, and then click Create.

Create API Connect Instance

2

Create a Node-RED service instance

Create an instance of the Node-RED Starter application. Ensure that the Lite plan is selected, and then click Create.

Create Node-RED Instance

Click Visit App URL, and then use the wizard to configure Node-RED.

Be sure that you note the base url of Node-RED, such as: https://client-app-demo.eu-gb.mybluemix.net/.

Note Node-RED base url

3

Configure API Connect

  1. Note the endpoint url in API Connect:
    1. On the API Connect Dashboard, click Sandbox.
    2. Select Settings.
    3. Select Gateways.
    4. Note the Endpoint URL.

Note the endpoint URL

  1. Create APIs for OAuth(Confidential mode), OAuth(Public mode), and Application.

For this tutorial, we require API configurations for OAuth(Confidential mode),OAuth(Public mode) and Application. You’ll import the configuration files, which are available in my GitHub repo, into IBM API Connect.

Create APIs

Create an API for OAuth Confidential mode

  1. On the API Connect Dashboard, select Drafts.
  2. Select APIs
  3. Click Add, and then select Import API from a file or URL.
  4. Select Or import from URL.
  5. Enter the URL https://raw.githubusercontent.com/IBM/api-connect-oauth-tutorial/master/resources/oauth_confidential_endpoint.yaml.
  6. On the design tab for the API, select OAuth 2.
  7. Scroll down to the Authentication section. For the Authentication URL, specify the Node-RED base URL that you noted earlier, but add /authenticate. For example: https://client-app-demo.eu-gb.mybluemix.net/authenticate. You’ll create a dummy authentication service in subsequent steps.
  8. Click the Save icon.

Create an API for OAuth Public mode

  1. On the API Connect Dashboard, select Drafts.
  2. Select APIs
  3. Click Add, and then select Import API from a file or URL.
  4. Select Or import from URL.
  5. Enter the URL https://raw.githubusercontent.com/IBM/api-connect-oauth-tutorial/master/resources/oauth_public_endpoint.yaml.
  6. On the design tab for the API, select OAuth 2.
  7. Scroll down to the Authentication section. For the Authentication URL, specify the Node-RED base URL that you noted earlier, but add /authenticate. For example: https://client-app-demo.eu-gb.mybluemix.net/authenticate. You’ll create a dummy authentication service in subsequent steps.
  8. Click the Save icon.

Create an API to the client application

  1. On the API Connect Dashboard, select Drafts.
  2. Select APIs
  3. Click Add, and then select Import API from a file or URL.
  4. Select Or import from URL.
  5. Enter the URL https://raw.githubusercontent.com/IBM/api-connect-oauth-tutorial/master/resources/app_endpoint.yaml.
  6. On the design tab for the API, select Security Definitions.
  7. Scroll down to the Authentication section. For the Authorization URL, specify the endpoint URL for API Connect that you noted earlier, but add /conf/oauth2/authorize. This authorization URL is for confidential mode. You’ll need to change this URL when you use Public mode.
  8. For the Token URL, specify the endpoint URL for API Connect that you noted earlier, but add /conf/oauth2/token. This authorization URL is for confidential mode. You’ll need to change this URL when you use Public mode.
  9. Click the Save icon.
  10. Select the Assemble tab. Select Invoke. For the URL, specify the Node-RED base URL that you noted earlier, but add /app. For example: https://client-app-demo.eu-gb.mybluemix.net/app.
  11. Note the API URL.

Note the URL for the API. The API URL is the endpoint URL for API Connect that you noted earlier, but with /appendpoint/ops at the end.

Create a product and publish it

  1. On the API Connect Dashboard, select Drafts, and then select Products.
  2. Select Add > New Product.
  3. Enter a title, name, and version, and then click Create product.
  4. On the Design page, select APIs in the left-nav to scroll down to that section. Then, click the + to add APIs.
  5. Select all three APIs that we just defined. Click Apply.
  6. Click the Save icon.
  7. Click the Stage icon, and then select Sandbox.
  8. Go to the Dashboard, and select Sandbox.
  9. Select the staged product. From the menu, select Publish.
  10. On the dialog that is displayed, click Publish.

Create product and publish

Create an app on the developer portal

  1. On the Sandbox dashboard, select Settings.
  2. From the left-nav, select Portal.
  3. From the Select Portal list, select IBM Developer Portal.

    Enable IBM Developer Portal

  4. Under the Select Portal list, click the Portal URL link to open up the portal.

  5. On the portal page, click Create an account. Specify the account details, and click Create new account.
  6. Activate the account by clicking the URL that is sent to the email you specified.
  7. Log in to the portal with the credentials you specified.
  8. In the portal, click Apps.
  9. Click Create an app.
  10. Enter a title and description for the app. For the OAuth Redirect URI, specify the Node-RED base URL that you noted earlier, but add /appredirect. Then, click Submit. Be sure to note the Client ID and the Client Secret that is generated for this app.
  11. On the portal page, select API Products. Then, select the product that we just created and published, and then click Subscribe to subscribe to the default plan.

Create app

4

Deploy the client application

The client application has been implemented using Node-RED. The Node-RED flow is available as a JSON file in my GitHub repo.

The Node-RED flow has a dummy authentication endpoint, and an application endpoint that demonstrates the working of the OAuth flows.

  1. To Import the Node-RED flow, follow these steps:

    1. Copy the raw contents from the JSON file.
    2. Go to the Node-RED flow editor.
    3. Select Import, and then select Clipboard.
    4. Paste the copied contents of the JSON file.
    5. Click Import.
  2. Click Deploy to deploy the Node-RED flow.

Import Node RED

5

Run the application

  1. Configure the application by going to the Node-RED base URL that you noted earlier, but add /configuredemo. Specify all the details. Specify the appropriate authorize and token URLs depending on whether the mode is confidential or public. Click Configure.

  2. After your configure the application, the `/logindemo page opens up. Select either the confidential mode or public mode, select the scheme, and click Login.

The token is generated and the application API is accessed successfully.

In the Node-RED debug window, we can see the request details that are generated for the selected OAuth implementation mode and scheme.

Here is a demo of the confidential mode:

Create app

Here is a demo of the public mode:

Create app

Summary

In this tutorial, we were able to access an application API with all the OAuth 2.0 modes and schemes that are supported by IBM API Connect. We also saw the URL, headers, and payload for the http requests that were generated based on the selected OAuth scheme.

Balaji Kadambi