Tutorial: Securing an API with a client ID and client secret

This tutorial shows you how to secure an API so that a calling application must supply a client ID and a client secret in IBM® API Connect Version 5.0.7 and later. This option is similar to requiring a user ID and password to be supplied.

Before you begin

Note: For tutorials about working with the developer toolkit in IBM API Connect Version 5.0.6 and earlier, see Developer toolkit tutorials for V5.0.6 and earlier.

The following diagram shows the sequential flow through the IBM API Connect Developer toolkit tutorials for working with API definitions that call an existing endpoint. Before beginning a tutorial, ensure that you have completed the previous tutorials in the sequence. You can click a tutorial in the diagram to open the instructions for that tutorial.

Tutorial flow diagram for API definitions that call an existing endpoint

About this tutorial

You will modify the security settings for the Branches API, which you created in the tutorial Tutorial: Creating an invoke REST API definition, so that a calling application must supply a client ID and a client secret, then you will attempt to call the Branches API with and without the client ID and client secret, to verify that the client ID and client secret are required.

You will complete the following lessons:

Setting the identification mechanism of an API

To modify the security settings for the Branches API so that a calling application must supply a client ID and client secret, complete the following steps:

Change directories to your LoopBack® project and enter the following command:
```
apic edit
```
After a brief pause, the console displays this message:
```
Express server listening on http://127.0.0.1:9000
```
API Designer opens in your web browser, initially displaying the login page if you haven't logged in recently.

Note: The login page prompts you to Sign in with IBM Cloud. Enter your IBM Cloud credentials, which authenticates you on IBM Cloud and provides access to the API Manager features such as Publish, Explore, and Analytics. You will continue to work in API Designer locally to create APIs, models and data sources.
Note: If you need to run the editor on a different port, use the following command:
```
PORT=port_number apic edit
```
```
set PORT=port_number && apic edit
```
where port_number is the port number to use.
Click APIs, then click the Branches REST API that you created in the tutorial Tutorial: Creating an invoke REST API definition.
Navigate to the Security Definitions section.
Note that, by default, a Client ID security definition already exists for your API.
Click the Add Security Definition icon in the Security Definitions section, then select API Key. A new API Key security definition displays in the Security Definitions section.
Change the value of the Name field to Client secret.
Leave the value of the Parameter Name field as X-IBM-Client-Secret. You have defined a new security scheme.
Navigate to the Security section.
In the Security section, select Client secret (API Key), in addition to Client ID (API Key) which should already be selected by default.
Click the Save icon to save your changes.

You have modified the operation so that a calling application must supply a client ID and client secret.

Calling an API by using a client ID and client secret

Now that you have determined the client ID and client secret for the Baggage Tracker application, you can supply them when calling the BankA API. For the purposes of this tutorial, you call the Branches API by testing it in the API Designer Explorer.

To call the Branches API by using a client ID and client secret, complete the following steps:

Start the local test servers by completing the following steps:
1. In the test console at the bottom of the screen, click the Start the servers icon:
2. Wait until the Running message is displayed:
  Depending on your project configuration and whether other processes are running, a different port number might be displayed.
Note: If your Micro Gateway is already running, you must restart it before you can test your changes, by clicking the Restart the servers icon
.
Click Explore, then click Try it.
Scroll down to the Identification section in the pane on the right.
The Client ID field contains the value default, and the Client secret field contains the value SECRET in redacted form; these are the default values that are used for testing in the API Designer Explorer.

When the API is published and becomes available to application developers through the Developer Portal, the API will be called by using application specific client ID and client secret values; for more information, see Adding an application.
Remove the client ID and client secret values and click Call operation to test the API. The call fails.
Restore the client ID and client secret value by entering default in the Client ID field and SECRET in the Client secret field, and click Call operation to test the API. The Branches response is returned correctly:

What you did in this tutorial

In this tutorial, you completed the following activities:

Set the identification mechanism of an API.
Called an API by using a client ID and client secret.