This documentation is for WSO2 Identity Server 5.1.0 . View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

OAuth 2.0 authorization servers provide support for four main grant types according to the OAuth 2.0 specification. It also has the flexibility to support any custom grant types. This topic provides instructions on how to implement a custom grant type for OAuth 2.0 authorization server and how to extend the behavior of default grant types.

The WSO2 Identity Server is used as the OAuth 2.0 authorization server implementation, which is an open source implementation.

Implementing a new grant type

When using the WSO2 Identity Server, you must do the following to implement a new grant type.

  1. Implement the following two extensions.
    • 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 the “AuthorizationGrantHandler” interface or by extending “AbstractAuthorizationGrantHandler”. In most cases, it is enough to extend the “AbstractAuthorizationGrantHandler” in the WSO2 OAuth component.
    • GrantTypeValidator - This is used to validate the grant request that is sent to the /token endpoint. 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.
  2. When implementation is done, package your class as a .jar file and place it in the <IS_HOME>/repository/component/lib directory.
  3. Then you need to register the grant type with unique identifier. You can do this by adding new entry in the <IS_HOME>/repository/conf/identity.xml file. Here, you need to define your implementation class. These changes need to be made under the <OAuth><SupportedGrantTypes> element.

    <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>

A sample of the above scenario is found below.

Using the grant type sample

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.

The request to the /token API must contain the following two request parameters.

  • grant_type=mobile
  • mobileNumber=044322433

The new grant type project sample can be accessed here. The grant handler and validator class is found inside “org.soasecurity.is.oauth.grant.mobile” package. This can be modified as required.

  1. Copy the .jar file into the <IS_HOME>/repository/component/lib directory. You can also modify the project and build it using Apache Maven 3.
  2. Configure the following in the <IS_HOME>/repository/conf/identity.xml file under 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>
  3. Restart the server.
  4. Configure the new OAuth grant type.
  5. Send the grant request to the /token API using a cURL command.
    1. The HTTP POST body must contain the following two parameters: grant_type=mobile and mobileNumber.

      grant_type=mobile&mobileNumber=0333444
    2. The following is a sample cURL command.

      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
    3. You receive the following JSON response with the access token.

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

Customizing an existing grant type

As an alternative to creating a custom OAuth grant type, you can customize one of the existing grant types. The following two classes are sample implementations of customizing the password grant type. However, you can do it for any grant type.

This section provides instructions on how to do the second implementation.

  1. Copy the .jar file into the <IS_HOME>/repository/component/lib directory. You can also modify the project and build it using Apache Maven 3.
  2. Configure the following in the <IS_HOME>/repository/conf/identity.xml file under the <OAuth><SupportedGrantTypes> element.

    <SupportedGrantType>
    	<GrantTypeName>password</GrantTypeName>
    	<GrantTypeHandlerImplClass>org.soasecurity.is.oauth.grant.password.ModifiedAccessTokenPasswordGrant</GrantTypeHandlerImplClass>
    </SupportedGrantType>
  3. Restart the server.

  4. Configure the OAuth grant type you customized.
  5. Send the password grant request to the /token API using a cURL command similar to the following.

    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 an email address.

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