WSO2TORIAL: Creating a custom OAUTH2 Grant type

In a previous blog we looked into the OAUTH2 grant types that are used within the WSO2 API Manager. We only touched on the part on custom OAUTH2 grant types. In this blog we will look in more detail at the custom types, discuss the business case for that and of course look on how you would typically do that.

WSO2 Identity Server or API Manager?

We could use WSO2 IS as our OAUTH2 server but it is not needed since the API Manager includes the key manager feature, that is where you create a custom OAUTH2 grant.

So if you haven’t done so, download WSO2 API Manager 2.1.0 and deploy it somewhere that allows you to access it, both the Management UI as well as the directory structure.

Business case

Why would you create a custom grant type? One of the business cases would be that you would like to use a different unique identifier or combination of identifiers to get a token.

High Level steps

As with many WSO2 extensions, it is actually a java program that implements two extensions:

1. an extention of the Abstract or an new implementation of the AuthorizationGrantHandler;
2. extension of the GrantTypeValidator.

The first extension describes how the grant type must be validated and how the token must be issued. The second extension defines what  parameters are in the request and  define validation of them.

When the extensions are ready (in a mvn project structure as described below), build the jar file and include it in [APIM-HOME]/repository/components/lib.

Register the custom grant type, configure the identity.xml file in <APIM_HOME>/repository/conf/identity by adding a new entry under the <OAuth><SupportedGrantTypes>.

After that you need to restart the API Manager.

So in three steps you can create a custom grant type and include it in the API Manager.

Creating the extensions

Normally, you create a new Maven project and create the structure that is required. But why would you reinvent the wheel? Especially for this blog it is good to use the source of an existing grant that is already a Maven project. So let’s look at what is available and work from there.

After downloading it from https://docs.wso2.com/download/attachments/60493976/custom-grant.zip?version=1&modificationDate=1452601958000&api=v2 we can unzip it to a location and import it to Eclipse to see what is inside.

Click Next

Enter the location where you unzipped the custom grant zipfile and click finish.

The new grant type project sample can be accessed here. The grant handler and validator class is found inside org.wso2.sample.identity.oauth2.grant.mobile  package. This can be modified as required. There are more grant types in the sample, we leave them out of scope in this blog.

Inside the java files

Let us look in the MobileGrant.java  first

We see a number of steps:

1. Naming of the package and importing Log capabilities
2. Extending the Abstract handler and defining the MOBILE_GRANT_PARAM
3. Sending a log message, getting the parameters from the call and if the parameter equals “mobileNumber”, get the mobileNumber.

At this point we broke the flow down, but there is of course more.

We validate the mobile number which is a separate routine.

This is of course nonsense, because the check is if it starts with 033 but goes to show the mechanism.

You can do whatever you like there, as long as you return true or false.

Getting back to the routine, we just look at the returned value and either set the authenticate user and other attributes or set the response headers that the number is invalid.

After that it is just returning status.

The MobileGrantValidator is the other file. In this file we actually set the required parameters for the call.

We do a mvn clean install to create a .jar file

We move it to the [APIM-HOME]/repository/components/lib. It will be not hot deployed  and we need to restart to deploy and picked up by the API Manager. However, we do need to include the grant type in the [APIM_HOME]/repository/conf/identity/identity.xml file under the <OAuth><SupportedGrantTypes> element. The GrantTypeName is yours to chose, the two xmls tags below are of course in the jar file we built and should reflect the two classes:

1. wso2.sample.identity.oauth2.grant.mobile.MobileGrant;
2. wso2.sample.identity.oauth2.grant.mobile.MobileGrantValidator.

The whole section will look something like this:

These changes however need a server restart in order to be added  to the API Manager.

Testing it out

The sample demonstrated here defines a new sample grant type called the “mobile” grant type. It is similar to the password grant type and the only difference is that a mobile number will be passed through instead of a password. The request to the /token API must contain the following two request parameters, for example:

• grant_type=mobile
• mobileNumber=0333444

One way to test it out is to define an Service Provider in the API Manager and configure it to allow the new grant-type.

Configure the new OAuth grant type

In order to test the new grant grant type we need to sign in to the WSO2 API Manager. We will use the Management UI. We will do that using a service provider because we need an application to get a client key and client secret.

So log in to the API Manager with for instance the admin / admin credentials. On the main tab Add a Service provider for instance called MyTestProvider

Enter your username and password to log on to the Management Console.

1. Navigate to the Mainmenu to access the Identity Click Add under Service Providers.
2. Fill in the Service Provider Nameand provide a brief Description of the service provider. See Adding a Service Provider for more information.

Open Inbound Authentication Configuration and  open OAuth/OpenID Connect Configuration and click on Configure.

Enter a callback url for example http://localhost:8080/playground2/oauth2client and click Add. This application is included in the samples for the Identity Server that need to be downloaded since they are not part of the default distribution of Identity Server. See this blog WSO2EASY: Adding Samples to WSO2 Identity Server how to do that. You will need to run the warfile on a Tomcat server (version 7.x) for it to be available.

As a result the OAuth Client Key and OAuth Client Secret will now be shown.

We will now use cURL to send a grant request to the TokenAPI (part of the API’s the API Manager uses internally).

The client key and secret you have gotten must be used in the cURL call and the HTTP body should habe the two parameters as we defined them mandatory.

grant_type=mobile&mobileNumber=0333444

cURL is a command line tool so go to the cmd window or terminal and send the following

curl --user clientid:clientsecret -k -d "grant_type=mobile&mobileNumber=0333444" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:9443/oauth2/token

The clientid:clientsecret needs to be taken from the service provider. These are unique values, you can’t type them from this blog.

As a response you will get a similar JSON response with the access token. On the console the log is shown that the mobile grant.

{"token_type":"bearer","expires_in":2823,"refresh_token":"26e1ebf16cfa4e67c3bf39d72d5c276","access_token":"d9ef87802a22cf7682c2e77df72c735"}

Alternatively, try to change the mobile number to anything other than starting with 033 and see that you get an error.

This example of a custom grant type is of course simple but it shows the power of a custom grant type and it is up to you to extend the example to your needs or liking.

Thanks to Rob Brouwers for reviewing this blog.

If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.