Custom grant type with OAuth 2.0

OAuth 2.0 Authorization servers support for four main grant types according to the specification. Also it has given the flexibility to support any custom grant types. Today, I am going to implement a custom grant type for OAuth 2.0 Authorization server. Also we are going to see how we can extend the behavior of default grant types.

I am using WSO2 Identity Server as OAuth 2.0 Authorization Server implementation, which is an open source implementation.

Implementing new grant type

Step 1. If you are using Identity Server, you need to implement two extensions for this.

• GrantTypeHandler  –  This is the implementation of the grant type.  Here you can implement the way, it must be validated and how token must be issued. You can write the new implementation by implementing “AuthorizationGrantHandler” interface or by extending the “AbstractAuthorizationGrantHandler”. Most of the cases, It is enough to extend the “AbstractAuthorizationGrantHandler” in WSO2 OAuth component.

• GrantTypeValidator – This is used to validate the grant request that is sent to the /token end point. You can define what parameters must be in the request and define the validation of them. You can write the new implementation by extending the “AbstractValidator” in Apache Amber component.

Step 2. When implementation is done, you need to package your class as jar file and put in to the <IS_HOME>/repository/component/lib directory.

Step 3. Then you need to register the grant type with unique identifier. You can do it by adding new entry for identity.xml file. Here, you need to define your implementation class.

<SupportedGrantType>
 <GrantTypeName>grant type identifier </GrantTypeName>
 <GrantTypeHandlerImplClass>full qualified class name of grant handler</GrantTypeHandlerImplClass>
 <GrantTypeValidatorImplClass>full qualified class name of grant validator</GrantTypeValidatorImplClass>
 </SupportedGrantType>
 <SupportedGrantType>

Sample Grant Type implementation

I am going to define new sample grant type called, “mobile” grant type. It is same as password grant type, only different that you need to pass the mobile number.

Request to /token API must contain following two request parameters

•  grant_type=mobile
• mobileNumber=044322433

Please find my new grant type project from here, You can find the grant handler and validator class inside “org.soasecurity.is.oauth.grant.mobile” package. You can modify them as you want.

Try Out

Step 1. Copy jar file in to <IS_HOME>/repository/component/lib (You can even modify the project and build using maven 3)

Step 2. Configure following in the identity.xml file inside the <OAuth><SupportedGrantTypes> element

<SupportedGrantType>
<GrantTypeName>mobile</GrantTypeName>
<GrantTypeHandlerImplClass>org.soasecurity.is.oauth.grant.mobile.MobileGrant</GrantTypeHandlerImplClass>
<GrantTypeValidatorImplClass>org.soasecurity.is.oauth.grant.mobile.MobileGrantValidator</GrantTypeValidatorImplClass>
</SupportedGrantType>

Step 3. Restart the server.

Step 4. You can register, OAuth application as mentioned in there.

Step 5. Then send the grant request to /token API using curl.

HTTP POST body must contains  following two parameters.  i.e  grant_type=mobile  and mobileNumber

grant_type=mobile&mobileNumber=0333444

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

you will receive following json response with access token

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

Customizing existing grant type

You can even customize existing grant types. I have implemented following two class to customize the password grant type. However, you can do it for any grant type.

• RoleBasedPasswordGrant  – This does some RBAC validation apart from the authentication before granting.
• ModifiedAccessTokenPasswordGrant  – This customized the access token value as i wanted.

As an example, if you want to try out the second implementation.

Step 1. Copy jar file in to <IS_HOME>/repository/component/lib (You can even modify the project and build using maven 3)

Step 2. Modify password grant type class in the identity.xml. It would be as follows.

<SupportedGrantType>
<GrantTypeName>password</GrantTypeName>
<GrantTypeHandlerImplClass>org.soasecurity.is.oauth.grant.password.ModifiedAccessTokenPasswordGrant</GrantTypeHandlerImplClass>
</SupportedGrantType>

Step 3. Restart the server.

Step 4. You can register, OAuth application as mentioned in there.

Step 5. Then send password grant request to /token API using curl.

curl --user j35X8UIc5KXMJXgcWIChVMffv6ca:6FOPU8JrQDZqMu4GugfHpbtD_vsa -k -d "grant_type=password&username=admin&password=admin" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:9443/oauth2/token

You can see the modified access token with some email address.

{"token_type":"bearer","expires_in":2955,"refresh_token":"6865c8d67b42c0c23e634a8fc5aa81f","access_token":"[email protected]"}

Thanks for reading …!!!