WSO2 Tutorial 7 min

WSO2TORIAL: Creating a custom OAUTH2 Grant type

Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
WSO2Torial witruimte 1

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.

creating custom oauth2 grant type-import to eclipse.png

Click Next

custom oauth2 grant type - location unzip custom grant zipfile.png

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

custom oauth2 grant type - sample.png

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

custom oauth2 grant type-mobilegrant.java.png

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.

custom oauth2 grant type -validate the mobile number-1.png

custom oauth2 grant type -validate the mobile number-2.png

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.

custom oauth2 grant type - mibilegrantvalidator.png

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:


custum oauth2 grant type - server restart.png

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

custom oauth2 grant type - add new service provider.png

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.

custom oauth2 grant type - Service Providers.png

custom oauth2 grant type - Register New Application

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.

custom oauth2 grant type - OAuth Client Key and OAuth Client Secret.png

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.


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.


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 SupportWSO2 Development SupportWSO2 Operational Support and WSO2 Training Programs.

The Identity and Access Management selection guide

Get it now
We appreciate it
Care to share

Please select one of the social media platforms below to share this pages content with the world