![DataPower Gateway only](../buildfiles/icon_datpowergtw_only.png)
Tutorial: Securing an API by using OAuth 2.0
This tutorial shows you how to secure an API by using OAuth 2.0 so that an application can access the API on a user's behalf, in IBM® API Connect Version 5.0.6 and earlier.
Before you begin
To complete this tutorial, you need an environment capable of sending HTTP requests and receiving HTTP responses. In these instructions, the curl command is used in a command line interface to demonstrate the OAuth flow without the need to write any application code. When you implement the OAuth flows for your application, make the same HTTP REST calls as used with curl in this tutorial.
![Tutorial flow diagram for API definitions that call an existing endpoint](tutorial_flow_diagram_existing_endpoint_secureoauth.jpg)
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 can make use of OAuth 2.0 to access the API on behalf of a user without requiring the user's password.
In this tutorial you will complete the following lessons:
- Choosing your OAuth Scheme
- Creating an OAuth 2.0 provider API
- Configuring the API Security Scheme
- Acquiring Access Tokens for Individual Schemes
- Using the Access Token
In OAuth 2.0, the following three parties are involved:
- The user, who possesses data that is accessed through the API and wants to allow the application to access it
- The application, which is to access the data through the API on the user's behalf
- The API, which controls and enables access to the user's data
Using OAuth 2.0, it is possible for the application to access the user's data without the disclosure of the user's credentials to the application.
The API will grant access only when it receives a valid access token from the application. How the application obtains an access token is dependent upon the OAuth scheme that is in use.
In this tutorial, you will be able to implement and test any of the following six OAuth schemes: implicit flow, application flow, confidential password flow, public password flow, confidential access code flow, and public access code flow. More information about these schemes is available in the following section.
Choosing your OAuth scheme
If you already know which OAuth scheme you intend to use, skip this section and proceed to Creating an OAuth 2.0 provider API.
To choose an OAuth scheme, you must first establish whether your implementation is considered public or confidential. This will narrow your choices to three schemes. A brief outline of each scheme and the characteristics of the three public and three confidential schemes follows:
- Confidential
A confidential scheme is suitable 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.
- Application flow
In the application flow scheme, the user is not required to provide authorization at any stage. Instead, the application uses its client secret to obtain an access token. In this case, it is critical that the client secret is kept safe.
- Password flow
In the password flow scheme, the user provides the application with a user name and password that can be used to access the user's data. Following this, the client will directly contact the provider API to request an access token. In this case, trust must exist between user and application because the user's password is revealed to the application. However, this still has an advantage over the application using the password directly, because the validity of the access token or client ID can later be revoked without impacting other applications that do not need their access revoked. However, the application must be trusted to not store the user name and password.
- Access code flow
In the access code flow, the application has the user provide authorization through a form provided by the gateway server, which, if they grant authorization, provides an authorization code to the application. The application sends the authorization code to the provider API and is granted an access token in return.
- Application flow
- Public
A public scheme 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.
- Implicit flow
In the implicit flow scheme, the application requests an access token from the gateway server and the user grants permission, at which point an access token is provided to the user, who must then pass the token to the application
- Password flow
In the password flow scheme, the user provides the application with a user name and password that can be used to access the user's data. Following this, the client will directly contact the server to request an access token. In this case, trust must exist between user and application because the user's password is revealed to the application. However, this still has an advantage over the application using the password directly, because the validity of the access token or client ID can later be revoked without impacting other applications that do not need their access revoked. However, the application must be trusted to not store the user name and password.
- Access code flow
In the access code flow, the application has the user provide authorization through a form provided by the gateway server, which, if they grant authorization, provides an authorization code to the application. The application sends the authorization code to the provider API and is granted an access token in return.
- Implicit flow
Creating an OAuth 2.0 provider API
To create an OAuth 2.0 provider API, complete the following steps:
- In a command window, change to the project folder that you created in the tutorial Tutorial: Creating an invoke REST API definition.
- 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:where port_number is the port number to use.PORT=port_number apic edit
set PORT=port_number && apic edit
- In the API Designer, click the APIs tab.
- Click .
- Complete the fields according to the following table:
Table 1. Field Contents Title OAuth Endpoint API Name oauth-endpoint-api Version 1.0.0 Base Path /oauth-end Description
Provides operations for acquiring access tokens for other APIs. Click Next, ensure that Don't add to a product is selected and then click Add.
Click Create API.
- In the OAuth 2 section, configure the OAuth settings of your
provider API.
- Click the Save icon
to save your changes.
Configuring the API security scheme
Acquiring access tokens for individual schemes
Using the access token
This section is common to all the OAuth schemes. You will access the Branches API and be authenticated.
What you did in this tutorial
In this tutorial you have:
- Chosen your OAuth Scheme.
- Configured the API Security Scheme.
- Acquired an access token for your chosen scheme.
- Used the access token.
What to do next
- When acquiring an access token, use the calculate_loans scope, instead of the view_branches scope, to verify that a code requested for only the scope specified by the secured API can be used to access the API.
- Repeat the tutorial for a different OAuth flow.