Sunday, January 27, 2013

How to write a Custom Authentication Handler for WSO2 API Manger ?

WSO2 API Manager provide OAuth2 bearer token as its default authentication mechanism. But we can extend it to support any of the authentication mechanism other than the bearer token authentication.

This post explains, how we can write a custom authentication handler for WSO2 API Manager. 

Implementation of the default authentication handler used in WSO2 API Manger can be found here. As the same way, we can write our own authentication handler class by extending '' class.

In the authentication handler implementation class, we have to implement the 'handleRequest()' and 'handleResponse()' methods. See the sample '' class given bellow. 

import org.apache.synapse.MessageContext;
import org.apache.synapse.core.axis2.Axis2MessageContext;

import java.util.Map;

public class CustomAPIAuthenticationHandler extends AbstractHandler {

    public boolean handleRequest(MessageContext messageContext) {
        try {
            if (authenticate(messageContext)) {
                return true;
        } catch (APISecurityException e) {
        return false;

    public boolean handleResponse(MessageContext messageContext) {
        return true;  

    public boolean authenticate(MessageContext synCtx) throws APISecurityException {
        Map headers = getTransportHeaders(synCtx);
        String authHeader = getAuthorizationHeader(headers);
        if (authHeader.startsWith("userName")) {
            return true;
        return false;

    private String getAuthorizationHeader(Map headers) {
        return (String) headers.get("Authorization");

    private Map getTransportHeaders(MessageContext messageContext) {
        return (Map) ((Axis2MessageContext) messageContext).getAxis2MessageContext().

  • Build the above class and copy the jar file to <AM_HOME>/repository/components/lib folder where <AM_HOME> is the root of the WSO2 API Manager distribution.
  •  You can engage this handler to the API through the Management Console. Log in to the console and select 'Service Bus > Source View' in the 'Main' menu.
  •  In the ESB configuration that opens, you can see following line as the first handler in the API, which is the current authentication handler used in API Manager. 
<handler class=""/>

Replace it with the one that we created.

<handler class=""/>


  1. as a PhD understudy you will do far reaching examination, for the purpose that is what the doctoral degree descends to. The most critical part of the doctoral system is the exposition the PhD understudies need to compose.

  2. Hi,

    I have created a custom class as per your instruction in the post. But when i place the jar in repository/components/lib wso2 is not recognizing the jar and it is throwing class not found exception.

    So I place the jar in extension folder, but after restart it is throwing class not found exception of APIAuthenticationHandler not CustomAPIAuthenticationHandler.

    So I removed the custom jar from extension folder and restarted the wso2 AM and it started with out any problem and the all the api settings was removed from the service bus configuration.

    My api manager version is 1.5.

    Please help me on this and guide me how to write a custom authentication or using googles oAuth in WSO2 AM.

  3. Hi Dinusha:
    Thanks for nice blog and is very helpful. I have question. How to return custom response code and message in DSS when the select query or stored procedure returns null data.
    SELECT custname, custadd from cust_table where custnum = : custnum

    Now this select query assume returns null(no data found for the customer number supplied )
    In that case, I want to return a JSON with error
    "Error" :

    "error_code" : 25,
    "error_msg" : "No customer found for :customer Number"
    "error_status" : "ERROR"

    Let me know if there is way to achieve with DSS.


  4. I think you are positing with the valuable information. SO when we are projected towards the better placement we can manage with the prior value. Thank you and please keep update like this.

    Hr Consultancy in Bangalore

    Hr Franchise in Bangalore

  5. Hope it may be useful at any costs.And please keep post like this. Really useful information. Thank you very much. And if you are looking for the best investment for your future join with us

    Medical Insurance Plans

    Health Insurance UAE

    Insurance Companies in Dubai

  6. Thank you for sharing. And if you are looking for the best relocation process can make easier by our beneficial relocation services with

    Warehouse for Rent Singapore

    Cheapest Movers in Singapore

    Cheapest Storage Space Singapore