[Article] How to Generate API Manager Access Tokens Using Multi-Factor Authentication

Table of Contents

• Introduction
• Applies to
• Table of contents
• Multi-factor authentication
• Setting up WSO2 API Manager and Identity Server
• Get access token using multifactor authentication demo
• Conclusion
• References

Applies to

Introduction

WSO2 API Manager provides a complete set of solutions to design, publish, and manage APIs. It also provides the capability to act as an API gateway to route API traffic and at the same time to allow different levels of user access strategies to exposed APIs. Authorized users may get unlimited access to secured APIs while non-authorized users are able to consume only publicly exposed APIs. This is done through the tokens generated over the OAuth2 framework.

In order to give accessibility to data exposed via APIs to the right person, we have to generate tokens for the user after ensuring the user’s authenticity. Multi-factor authentication provides another layer of security for user logon sequence by requesting another set of information before issuing the access token to the user. This makes it harder for someone who has stolen a password to gain data from the exposed APIs. WSO2 Identity Server is used to define multi-factor authentication steps in the user authentication sequence.

Multi-factor authentication

Most web applications make sure that users create a strong password to protect data and information. In the past, this has been sufficient, but in the modern business world, passwords are losing effectiveness as a sole line of defense against the increasing number of cyber security threats. The reason is that hackers are now more sophisticated in password cracking. Multi-factor authentication (MFA) is a solution that can address today’s challenges; MFA adds extra layers of protection on top of the user name-password authentication by adding further steps to basic login procedure. This means in order to authenticate a user to get certain data it asks the user to enter more than one form of data. This would typically include

• Something you know (the knowledge factor), e.g. a username and password
• Something you have physical access to (the possession factor), e.g. an app on a mobile phone
• Something you are (the inherence factor), e.g. a device that plugs into the computer to scan a fingerprint

It is a strong authentication mechanism because it helps to defeat hackers by requiring users to show multiple, simultaneous, but independent factors of verifying their identities. When you have to enter only your username and one password, that's considered as a single-factor authentication.

Setting up WSO2 API Manager and Identity Server

In this article, we describe a scenario where the user generates an access token using multifactor authentication to invoke an API published in WSO2 API Manager. For demonstration purposes, we use two authentication means. This idea can be extended for any number of authentication steps. Here, the user gets authenticated by these two steps:

1. Basic username - password authentication
2. Using Yahoo credentials

Here, we use authorization code grant type¹ as the authorization grant type to obtain an access token and refresh the token to invoke an API as we have to use a web-based authentication mechanism to authenticate the user by using the above-mentioned steps. The authorization code is obtained by using an authorization server as an intermediate server between the client and resource owner, which is the backend API. In this scenario, WSO2 Identity Server acts as the authorization server. Instead of requesting the resource directly from the backend API, the client directs the resource owner to an authorization server through a user-agent. Then the authorization server redirects the user-agent back to the client with the generated authorization code.

Since the resource owner directly interacts with the authorization server, the resource owner’s credentials won’t be shared with the client. The client requests an access token from the authorization server's token endpoint by using the received authorization code.

Figure 1 illustrates the message flow passes between servers and clients in this use case scenario. First the client subscribes to an API using a created application in the API manager. Given that we are using the authorization code grant type, the client can invoke the authorized API of the API Manager by using the consumer key received from that application; the request would then go to the identity server. The client is then redirected to the login page of identity server. After the basic credentials are entered, the request will direct to the Yahoo login page and client will be requested to enter Yahoo credentials. Thereafter, the client receives the authorization code that can be used to obtain an access token and a refresh token. The client can invoke the token API exposed by the API manager; the authorization code in the request message will be validated in the WSO2 Identity Server and it will send back the access token along with the refresh token to the client.

Figure 1

This article will provide a guidelines on how you can to setup WSO2 API Manager and WSO2 Identity Server to support this use-case scenario.

1. As the first step, let’s unpack both WSO2 API manager and WSO2 Identity Server; if both servers are running on the same machine, a port offset needs to be set. In this case, let’s set the port offset of the API manager server as 1. Port offset can be set in the configuration file {Product_Home}/repository/conf/carbon.xml as below.
   

   <Offset>1</Offset>

2. Then we can configure the identity server as a key manager for the API manager setup. For that, you can refer to the documentation².
3. Create and publish an API in the API manager in the publisher web app.
4. Open the API Store Web application in a browser and click the sign-up link that appears in the top, right-hand corner of the window, fill the sign-up form that appears and click the Submit button.
5. By default, this user is assigned to ‘Internal/subscriber’ role and only permitted to login and subscribe to APIs. However, as we need to have service providers and identity providers related tasks, we have to grant those permissions to the ‘Internal/subscriber’ role. For that, log into the identity server management console as the admin user and go to Configure > Users and Roles. Select ‘Roles’ and then ‘Internal/subscriber’ role. Click on ‘Permission’ and assign admin/manage permission as shown in Figure 2.
   
   

   Figure 2

6. Login to the store web application as the signed-up user. Create an application in the store application of the API manager and subscribe to the published API using the created application.
7. Generate consumer key consumer secret pair for that application.
8. Login to the identity server and list down the service providers. Then you will see that the created application is listed as a service provider (Figure 3).
   
   

   Figure 3

9. Click on the Edit button of the service provider and go to Inbound Authentication Configuration > OAuth/OpenID Connect Configuration. Then you will see that the consumer key and consumer secret of the application in API manager will be saved as OAuth Client Key and OAuth Client Secret, respectively. Click on the Edit button of the OAuth configuration. It will show the allowed grant types for this service provider. By default, the code grant type is not listed under allowed grant types. Tick on ‘Code’ and you will be asked to enter Callback Url. Callback URI is important as the authorization server will redirect the authorization code for the URI specified as the callback url (Figure 4).
   
   

   Figure 4

10. As the user is authenticated by his Yahoo credentials, we have to register Yahoo as an external identity provider. For this, go to Main > Identity > Identity Providers. In the added identity provider, set enable for Yahoo Configuration, which is categorized under Federated Authenticators as shown in Figure 5.
    
    

    Figure 5

11. The most important thing to do is to add Yahoo identity provider as an authentication step of the service provider. In the service provider configuration, select the ‘Advanced Configuration’ option under ‘Local & Outbound Authentication Configuration’. Here, you can add multiple authentication steps. This means that you can have a combination of local authenticators and federated authenticators. As we have already added Yahoo as a federated identity provider, it will be listed under ‘Federated Authenticators’. Add authentication Step 1 for local authenticator as basic and Step 2 for Yahoo federated authenticator as shown in the Figure 6 screenshot.
    
    

    Figure 6

Now the API manager and identity server have been setup and you can run the demo.

Get access token using multifactor authentication demo

First, the user has to invoke the authorize API exposed by the API manager. As the API manager will be running with port offset 1, the authorize API URL will be https://localhost:8244/authorize

• query component - response_type=code&client_id=<consumer_key>&scope=PRODUCTION&redirect_uri=<url_encoded_application_callback_url>
• headers - Content-Type: application/x-www-form-urlencoded

For example, the user can direct the user-agent/ browser to make the following HTTP request

https://localhost:8244/authorize?response_type=code&client_id=qRpi9pwfgC...

Then the client is redirected to enter the local username and password that are stored in the identity server user store (Figure 7).

Figure 7

Next, the browser will redirect to the Yahoo login page in order to provide Yahoo credentials to the authenticated user (Figure 8).

Figure 8

If the authentication is successful, the client is asked to allow the application to access his profile information. After access is granted, the authorize code will be redirected to the callback URL. For example https://client.example.com/?code=e75d11d42aaa3f563c6c2618b31c9d7

Then the client can use the received code to get the access token and refresh token to invoke the subscribed API.

curl -k -X POST -H "Authorization: Basic <base64_encoded(consumerKey:consumerSecret)>" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=<code>&redirect_uri=<url_encoded_application_callback_url>" https://<host>:<port>/token

A sample request would be,

curl -k -X POST -H "Authorization: Basic cVJwaTlwd2ZnQ29yTDkzdVgyTGZhTUNCMTJRYTp2T3dIcmJjZng4UTRiRWJYeGVOa2NKS09Xcmdh" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=2755972e47ee6cd802e6779e28841&redirect_uri=https%3A%2F%2Fclient.example.com" https://localhost:8244/token

At this point, the access token and refresh token are received in the response message. The access token can be used to invoke the API and if needed the refresh token can be used to re-generate access token.

Conclusion

MFA is a security system that requires more than one method of authentication from independent categories of credentials to verify the user’s identity in the login sequence. You can use the MFA mechanism to effectively authenticate users before issuing an access token from WSO2 API Manager to invoke an API. This will ensure the data is accessed by only an authorized user as well as ensure strong barriers to protect the data from hackers.

References

[1] https://tools.ietf.org/html/rfc6749#section-4.1

[2] https://docs.wso2.com/display/CLUSTER420/Configuring+the+Identity+Server+5.0.0+with+API+Manager+1.9.0