DEV Community: Athiththan

WSO2 API Manager & Custom Grant Handler

Athiththan — Sat, 11 Jan 2020 08:23:24 +0000

Greetings Everyone! 👋

In this medium, I will be 🚶 with you all on how to implement a custom Grant Handler for WSO2 Servers, especially for WSO2 API Manager when you are highly in need to introduce your own …

The demonstrations are presented and guided using WSO2 API Manager v2.6

Hmmm… alright. But,

Am I in need of one??? 🤔

Depends, maybe Yes, probably you are 💁.
Let me tell you a simple story, where a Goe-Location Startup needed to implement a custom grant to fulfill their security concerns and requirements.

Locus is a Geo-Location 🌏 service startup and it has been using the WSO2 API Manager to manage all of their exposed REST APIs and legacy SOAP services. Due to the increased demand for Geodata and analytics, one day the Locus team gathered to design a new architecture for their certified devices.

The 👮 platform security team and a group of Architectures 🤓 proposed Locus to isolate their certified devices from all registered devices by introducing a unique pattern for Access tokens 🔑.

When further breaking-down the features and analyzing the possibilities of implementing customized Tokens (you can refer to Customizing Opaque Access Token Generation), the devs found out that the WSO2 API Manager has extensions to develop and plug custom grants 🔐 and handlers.

👏 👏 👏 well-done guys… kudos for the effort and idea.

They re-engineered their architecture and introduced a custom grant named locus with the following required fields to fulfill their requirements

name: the unique ID name of the certified device
location: a regional code where the device has permissions and its current accessible location
key: a unique hash key embed to the certified device upon certification

I hope I made a good story to explain the case…
Let's keep the stories aside and dive into implementations.

🚧 Implementation

The WSO2 API Manager, or more likely to say the WSO2 Carbon platform is built in a way to extend and plug and play with the functions if required.

On a Personal Note
It is always good to think twice before introducing any customizations or extensions to the platform

So to achieve our needs, We have to extend the implementation of AbstractAuthorizationGrantHandler and push our enhancements to it.

Let's start by setting up a Maven project …
Create a new Maven project and the following dependencies in the POM

<dependency>
    <groupId>org.wso2.carbon.identity.inbound.auth.oauth2</groupId>
    <artifactId>org.wso2.carbon.identity.oauth</artifactId>
    <version>6.0.53</version>
</dependency>

If you encounter any dependency resolution errors or if you are not able to resolve the dependencies, add the following repositories to fetch 'em

<repositories>
    <repository>
        <id>wso2-nexus</id>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </repository>
</repositories>

<pluginRepositories>
    <pluginRepository>
        <id>wso2-nexus</id>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </pluginRepository>
</pluginRepositories>

With success, let's dive into the implementation of Grant Handlers. Grant Handlers are responsible to validate the Grant type and to issue Access Tokens.

Since we don't want to do any customizations to our Access Tokens, we will be only overriding the validateGrant() method to validate the inputs.

🌏 Locus Grant Handler

I've made it simple 🙌 for you all to save your precious time. You can complete development at the bottom of this story, but if you have time go through it (I've spent my time to write this one 😢)…

Given below is the complete implementation of the Locus Grant Handler. I've introduced a couple of isValid() methods to mock the validation and service calls to any defined data sources.

package com.grant.sample.handler;

import java.util.ArrayList;
import java.util.List;

import com.grant.sample.utils.LocusGrantConstants;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.wso2.carbon.identity.application.authentication.framework.model.AuthenticatedUser;
import org.wso2.carbon.identity.oauth2.IdentityOAuth2Exception;
import org.wso2.carbon.identity.oauth2.ResponseHeader;
import org.wso2.carbon.identity.oauth2.model.RequestParameter;
import org.wso2.carbon.identity.oauth2.token.OAuthTokenReqMessageContext;
import org.wso2.carbon.identity.oauth2.token.handlers.grant.AbstractAuthorizationGrantHandler;

public class LocusGrantHandler extends AbstractAuthorizationGrantHandler {

    private static final Log log = LogFactory.getLog(LocusGrantHandler.class);

    @Override
    public boolean validateGrant(OAuthTokenReqMessageContext tokReqMsgCtx) throws IdentityOAuth2Exception {
        log.info("Locus Grant Handler : Starting to validate grant");

        boolean isGrantValid = false;

        RequestParameter[] reqParams = tokReqMsgCtx.getOauth2AccessTokenReqDTO().getRequestParameters();

        String nameValue = null;
        String locationValue = null;
        String keyValue = null;

        for (RequestParameter param : reqParams) {
            switch (param.getKey()) {
            case LocusGrantConstants.LOCUS_NAME_GRANT_PARAM:
                nameValue = param.getValue() != null && param.getValue().length > 0 ? param.getValue()[0] : null;
                break;
            case LocusGrantConstants.LOCUS_LOCATION_GRANT_PARAM:
                locationValue = param.getValue() != null && param.getValue().length > 0 ? param.getValue()[0] : null;
                break;
            case LocusGrantConstants.LOCUS_KEY_GRANT_PARAM:
                keyValue = param.getValue() != null && param.getValue().length > 0 ? param.getValue()[0] : null;
                break;
            }
        }

        if (nameValue != null && locationValue != null && keyValue != null) {
            isGrantValid = (isValidName(nameValue) && isValidLocation(locationValue) && isValidKey(keyValue));

            if (isGrantValid) {
                AuthenticatedUser locusUser = new AuthenticatedUser();
                locusUser.setUserName(keyValue);
                tokReqMsgCtx.setAuthorizedUser(locusUser);
                tokReqMsgCtx.setScope(tokReqMsgCtx.getOauth2AccessTokenReqDTO().getScope());
            } else {
                ResponseHeader responseHeader = new ResponseHeader();
                responseHeader.setKey("LocusGrantError");
                responseHeader.setValue("Invalid Credentials");
                tokReqMsgCtx.addProperty("RESPONSE_HEADERS", new ResponseHeader[] { responseHeader });
            }
        }

        if (log.isDebugEnabled()) {
            log.debug("Locus Grant Handler : isGrantValid = " + isGrantValid);
        }

        return isGrantValid;
    }

    private boolean isValidName(String name) {
        // mocking database call with a sample list
        List<String> validNames = new ArrayList<>();
        validNames.add("locus-10-09874");
        validNames.add("locus-10-01219");

        return validNames.contains(name);
    }

    private boolean isValidLocation(String location) {
        // mocking the database with a sample list
        List<String> validLocations = new ArrayList<>();
        validLocations.add("LK-COLOMBO");
        validLocations.add("LK-KANDY");

        return validLocations.contains(location);
    }

    private boolean isValidKey(String key) {
        // mocking database call with a sample list
        List<String> validKeys = new ArrayList<>();
        validKeys.add("0987654321");
        validKeys.add("1234567890");

        return validKeys.contains(key);
    }
}

Find the util class implementation from here

A Toll-Free Tip 💪

It is required to create and set an AuthenticatedUser in the success flow to generate an access token and to bind it to that particular user. Otherwise, we'll end up in a broken flow.

Due to that, I have introduced and configured the key value of the Device to bound the generated access tokens

And that's all about the Grant handler …
Now let's configure our API Manager server to support the custom grant

WSO2 API Manager Configurations

Before configuring our API Manager pack, we have to build our Maven project. Execute the following command to build the project

mvn clean package

And copy and place the built JAR artifact inside the <APIM>/repository/components/lib directory.

Now direct to the <APIM>/repository/conf/identity directory and open up the identity.xml to add and support our locus grant with API Manager

<SupportedGrantTypes>
  ...
  <SupportedGrantType>
    <GrantTypeName>locus</GrantTypeName>
    <GrantTypeHandlerImplClass>com.grant.sample.handler.LocusGrantHandler</GrantTypeHandlerImplClass>
    <GrantTypeValidatorImplClass>com.grant.sample.validator.LocusGrantValidator</GrantTypeValidatorImplClass>
    <IdTokenAllowed>false</IdTokenAllowed>
  </SupportedGrantType>
  ...
</SupportedGrantTypes>

and that's all … 🎉

👏 Voila!!! 🙌

It is time to do an examination

Examine 🕵

Fire up the WSO2 API Manager server, and execute the request using either cURL or Postman or from your favorite REST client and take a note ✅

curl --location --request POST 'https://localhost:8243/token' \
   --header 'Authorization: Basic {base64<ClientID:Client Secret>}'\
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=locus' \
   --data-urlencode 'name=locus-10-09874' \
   --data-urlencode 'location=LK-COLOMBO' \
   --data-urlencode 'key=0987654321'

athiththan11 / LocusGrantHandler

A Custom Grant (Handler & Validator) Implementation for WSO2 API Manager

Locus Grant Handler

A custom Grant Handler & Grant Validator implementation for WSO2 API Manager

Implementation & Usage

The developed custom grant expects the following to authenticate and generate access tokens

name: a unique name
location: supported location
key: a unique key value

Given below are a set of sample values

name: locus-10-09874, ocus-10-01219
location: LK-COLOMBO, LK-KANDY
key: 0987654321, 1234567890

Configuring & Deploying

Use the following command to build the project

mvn clean package

Copy and place the built JAR artifact inside the <APIM>/repository/components/lib directory. Then navigate and open the <APIM>/repository/conf/identity/identity.xml and add the our custom grant under the <SupportedGrantTypes> section as follows

<SupportedGrantTypes&gt
    <SupportedGrantType&gt
        <GrantTypeName>locus</GrantTypeName&gt
        <GrantTypeHandlerImplClass>com.grant.sample.handler.LocusGrantHandler</GrantTypeHandlerImplClass>
        <GrantTypeValidatorImplClass>com.grant.sample.validator.LocusGrantValidator</GrantTypeValidatorImplClass>
        <IdTokenAllowed>false</IdTokenAllowed>
    </SupportedGrantType>
</SupportedGrantTypes>

Test Case

Fire up the WSO2 API Manager server by navigating to…

View on GitHub

Customizing Opaque Access Token Generation

Athiththan — Sun, 05 Jan 2020 13:04:55 +0000

Hola 👋

Greetings Everyone 😊 …
This is another medium on walking 🚶 and swimming 🏊🏼 through customizing the opaque access tokens using APIM Token Issuer when we do have a requirement issue

The demo is presented and walked-through using WSO2 API Manager v2.6

Whaaaaat? wait… Why? 🤔

You probably now have a question on why do we need to do that and does it actually matter… Let me give you a simple stupid occasion on when and where I actually need that.

RepoDeWS is a developer-management system which has a set of in-built management services in SOAP. These SOAP services are exposed as REST APIs with the help of WSO2 API Manager. Now the RepoDeWS team is having an undergoing process of security maintenance and they are expecting their users to invoke the APIs using access tokens with a "Dev-Hash" value appended to it.

This "Dev-Hash" value will be passed as a Header (devhash) when requesting an Access Token and will be appended during the generation of the opaque access token

Oh… I forgot to mention that the Dev-Hash value is a unique hash value given to a set of top-rated developers to enrich their API responses with the last accessed timestamps 😅

Let's just focus on the implementation and enhancements and will keep our use-cases behind that.

Implementation

To accomplish my simple requirement, We have to extend the implementation of APIMTokenIssuer and push our enhancements.

The APIMTokenIssuer is responsible for generating opaque access tokens and JWT tokens in the WSO2 API Manager platform

First, create a simple maven project and add the following dependency to the POM. This will help us to resolve most of the dependency issues when extending the APIMTokenIssuer class.

<dependencies>
 <dependency>
  <groupId>org.wso2.carbon.apimgt</groupId>
  <artifactId>org.wso2.carbon.apimgt.keymgt</artifactId>
  <version>6.5.222</version>
 </dependency>
</dependencies>

But, if you encounter any dependency problems or if you are not able to resolve the dependencies in the POM, then add the following as well …

<repositories>
 <repository>
  <id>wso2-nexus</id>
  <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
  <releases>
   <enabled>true</enabled>
   <updatePolicy>daily</updatePolicy>
   <checksumPolicy>ignore</checksumPolicy>
  </releases>
 </repository>
</repositories>
<pluginRepositories>
 <pluginRepository>
  <id>wso2-nexus</id>
  <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
  <releases>
   <enabled>true</enabled>
   <updatePolicy>daily</updatePolicy>
   <checksumPolicy>ignore</checksumPolicy>
  </releases>
 </pluginRepository>
</pluginRepositories>

Phew 😅
Managing dependencies is harder than managing expenses bruh 😬😬😭 …

Now let's jump into the extended implementation. Given below is the piece of code (I) developed to solve my own problem [Am I overreacting 😳 ? I think I am 😒]

package com.sample.token;
import org.wso2.carbon.apimgt.impl.APIConstants;
import org.wso2.carbon.apimgt.impl.utils.APIUtil;
import org.wso2.carbon.apimgt.keymgt.issuers.APIMTokenIssuer;
import org.wso2.carbon.identity.oauth2.token.OAuthTokenReqMessageContext;
import org.wso2.carbon.identity.oauth2.model.RequestParameter;
public class MyAPIMTokenIssuer extends APIMTokenIssuer {
  private static final Log log = LoggerFactory.getLog(MyAPIMTokenIssuer.class)
  @Override
  public String accessToken(OAuthTokenReqMessageContext tokReqMsgCtx) throws OAuthSystemException {
    // generate access token using super method
    String accessToken = super.accessToken(tokReqMsgCtx);
    String clientId = tokReqMsgCtx.getOauth2AccessTokenReqDTO().getClientId();
    Application application;
    try {
      application = APIUtil.getApplicationByClientId(clientId);
      String tokenType = application.getTokenType();
      // only acceptable for opaque access tokens and not JWT tokens
      if (!APIConstants.JWT.equals(tokenType)) {

        // retrieve all request parameters sent to the token request
        RequestParameter[] reqParams = tokReqMsgCtx.getOauth2AccessTokenreqDTO().getRequestParameters();
        for (int i = 0l i < reqParams.length; i++) {
          // check for devhash from the request parameters 
          // and append it to the access token
          if ("devhash".equals(reqParams[i].getKey())) {
            accessToken += reqParams[i].getValue()[0];
            break;
          }
        }
      }
    } catch (APIManagementException e) {
      log.error("Exception occured ", e);
    }

    return accessToken;
  }
}

I know right, it’s really hard to follow these things up 😐
Therefore, I give you a golden opportunity… Please go and find the sample implementation (gist) from GitHub Gist (save your time on reading this medium) and enjoy enriching it 😍

Your inner voice: Hmmm… Thanks for that. I have gone through the samples and copied everything from the given sources. Now, what should I do next? Where should I put these implementations???

Me: Ummm… I think I heard your inner voice. But thank you for the question.

As of next steps we have to build-up the maven project by executing the following command from a terminal

mvn clean package

And then copy and place the built JAR artifact from the target folder to the <APIM>/repository/components/lib directory.

And at last [Whoa…. the magical keyword 🤗😍], change the APIMTokenIssuer class representation to the MyAPIMTokenIssuer class by editing the <IdentityOAuthTokenGenerator> property in the <APIM>/repository/conf/identity/identity.xml.

<IdentityOAuthTokenGenerator>com.sample.token.MyAPIMTokenIssuer</IdentityOAuthTokenGenerator>

🎉 Voila!!! 🎉

Let’s do a test-run with our piece of code…

Keep Stacking!!!

Test Drive

Fire up the WSO2 API Manager server with the artifacts and the above-mentioned configuration changes.

Execute the following CURL command to generate an Opaque Access Token and let’s verify whether it got generated with the specified Dev-Hash value or not…

curl --location --request POST 'https://localhost:8243/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {Base64<ClientID>:<ClientSecret>} \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=admin' \
--data-urlencode 'password=admin' \
--data-urlencode 'scope=default' \
--data-urlencode 'devhash=af1c4ca13ab7d6c8d2a887d7ce8250a2'

And the response should be as follows with the Dev-Hash value appended to the Access Token

{
  "access_token": "25b9ded7-7441-3b69-bb6b-b1f1828bfff9af1c4ca13ab7d6c8d2a887d7ce8250a2",
  "refresh_token": "d86ac9b8-a3aa-3664-9d39-090ca49a9435",
  "scope": "default",
  "token_type": "Bearer",
  "expires_in": 3600
}

athiththan11 / Sample-APIMTokenIssuer

A simple custom APIM Token Issuer Implementation

Custom APIM Token Issuer

A sample extended APIMTokenIssuer implementation to append a custom value to the generated Opaque Access Tokens.

A Medium Blog: Customizing Opaque Access Token Generation

Implementation

This is a sample implementation to demonstrate on how-to extract a custom header sent to with the Token request and append it to the generate Opaque access token.

The custom header used here is called as devhash which is a hash value as data-urlencode with the Token request.

Given below is a sample /token requst

POST https://localhost:8243/token
Authorization: Basic <Base64 {Client ID}:{Client Secret}>
Content-Type: application/x-www-form-urlencoded
grant_type=password
username=admin
password=admin
scope=defualt
devhash=af1c4ca13ab7d6c8d2a887d7ce8250a2

curl --location --request POST 'https://localhost:8243/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header 'Authorization: Basic <Base64 {Client ID}:{Client Secret}> \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'username=admin' \
    --data-urlencode 'password=admin' \
    --data-urlencode 'scope=default' \
    --data-urlencode 'devhash=af1c4ca13ab7d6c8d2a887d7ce8250a2'

And the response should be as follows...

…

View on GitHub