SSL Mutual Authentication with WSO2 ESB

SSL Mutual authentication is a widely used authentication mechanism in B2B communication. This blog looks at the concept of SSL mutual authentication and how WSO2 ESB can support SSL Mutual authentication.

How mutual authentication works can be depicted in the diagram below


1. Client Request a resource from the server

2. Server presents the certificate

3. Client validates the certificate from the trust-store

4. Client present its certificate to the server

5. Server validates the certificate with the trust-store

6. Client access the protected resource

For this example we are using the mutual authentication client developed by Asela, and we will be creating our own KeyStore and a TrustStore (we will be using a single key store as both the KeyStore and the TrustStore) for the client service.

1. Lets start by modify the following {ESB_home}/repository/conf/axis2/axis2.xml file by un-commenting the following line in the ‘PassThroughHttpSSLListener’ transport receiver.

<parameter name="SSLVerifyClient">require</parameter>

2. Lets create the KeyStore for the client. We will be using the Java Keytool library for this. We will be executing the following command to create the keystore.

keytool -genkey -alias Client -keyalg RSA -keystore clientKeyStore.jks -keysize 2048

Keytool will prompt the user to enter a keystore password and other values pertaining to the keystore, enter these values and create the keystore. If you go to the folder from which you executed this command you will see the newly created keystore.

3. Next lets export a public certificate from the client Keystore that we can share with the ESB. To do this lets execute the following command.

keytool -export -keystore clientKeyStore.jks -alias Client -file client.crt

You will be prompted to enter the keystore password, enter the password you entered in the step1 .You will now see the client.crt file been created in the folder

4. We will be using the default WSO2Carbon keystore in the ESB, so lets create a public certificate from the wso2carbon keystore to be shared with the client. To do this execute the command below from the following location {ESB_Home}\repository\resources\security

keytool -export -keystore wso2carbon.jks -alias wso2carbon -file ESB.crt

You will prompted to enter the password of the keystore, enter ‘wso2carbon’ which is the default password.

5. Lets now import the certificates to each other’s trust store. Since we are using the same store as the keystore and the truststore for the client lets import the ESB certificate by executing the below command. (this command assume that both the client keystore and the ESB’s public certificate in the same folder)

keytool -import -keystore clientKeyStore.jks -alias wso2carbon -file ESB.crt

You will need to enter the client keystore password you entered in step1. You will also need to confirm the importing of the certificate to the keystore

6. Lets now import the clients certificate to the ESB. To do this execute the following command.

keytool -import -keystore client-truststore.jks -alias Client -file client.crt

As before you will need to enter the client-truststore password which is ‘wso2carbon’ and you would be prompted to add the certificate to the keystore. Once you approve the addition, the certificate would be added to the keystore.

7. Now lets invoke the MutualSSL client[1], for this client to work as we have configure the keystore name, the keystore password which we have set in step1, and the client keystore location. You will also need to provide the service URL of the secured service in the ESB.  Once this is set build the MutualSSLClient using maven. After the build is complete you will see the relevant jar file in the target folder. You can run this jar file from the WSO2 Application Server by following the information here [2]. You can use the try it client in WSO2 Application Server or a SOAP client to test the MutualSSLAuthentication client.

You would see the response from the service in the client



How to enabling wirelogs from the Carbon UI

Wirelogs are an important tool that can be used in debugging message flow. Wirelogs allow you to view the actual HTTP message that comes in and goes out from the ESB. Wirelogs can be enabled from the log4J.conf file and you would find more information on how to do this from the following blog [1], however this method would require server restarting and access to the file system of the ESB server.

Sometimes as a developer you would encounter a situation where you cannot restart or access the file system of the server to see wire logs. In that case you can enable wirelogs from the WSO2 ESB’s admin console UI. Wirelogs can be accessed from the admin console UI by following the steps given below.

1. Log into the admin console of the ESB.

2. Navigate to configuration tab and click on the logs icon as shown below.

3. Find “org.apache.axis2.transport” and change the log level to “Debug” as shown below.

You have now enabled wirelogs on the ESB instance.


How to access API definitions from the WSO2 API Manager

WSO2 API Manager provides an intuitive UI that can be used to add and configure API’s that are exposed via the API Manager. However not all the capabilities of an API can be manipulated from the API Publisher’s UI. Certain tweaks require the access to the API definitions directly. There are two possible ways of doing this.

1. Via the Management console of the API Manager

Access the Management console of the API Manager from the following URL and log-in using the admin credentials.


Once inside the management console, you can see the source view icon on the left hand side navigation bar as indicated below. Navigate to the source view page.

Here you would find all the API definitions, you can change the API definitions as required.

2. Directly accessing the API definition from the file system of the API Gateway.

API definition is stored in the file-system of the API Gateway, you can access this from the following folder path.


Each API is represented by a xml file. You can change the definition by changing the contents of the file. The changes would be hot deployed to the API Gateway.

Please be mindful of the changes you make as it affect the exposed API’s. API’s are defined in Apache Synapse hence you would need some level of knowledge on Apache Synapse to manipulate these files.

Returning multiple values from an Axis2 Service

Most of you who wants to create a quick Axis2 Service to mock a web-service would encounter a situation where you want to return more than 1 value from a service. You can simply return more than 1 value by returning a Hashmap. But this would return the values in the following format.

This would be a nightmare for any developer who would want to use the response from this service to perform message mediator or orchestration as all the XML elements share the same name ‘return’ making it impossible to extract values through XPath.

Solution for this problem is to return an object type from the Axis2 service. Given below is a sample code snippet on how this can be done.

Axis 2 service

WorkOrderResponse Class

By returning an object, the Axis2 service would return values with correct XML elements names. XML element names would correspond to the variable names in the object. Given below is a sample response from the above service.

ESB Guaranteed Delivery with client acknowledgement for synchronous clients

ESB Guranteed Delivery

A typical guaranteed delivery scenario covered as an Enterprise Integration ensures the delivery of a message to a given backend endpoint. As per this pattern the ESB would attempt to delivers the message to the backend endpoint and if it fails, the message would be stored and delivered once the backend endpoint becomes available. If the above guaranteed delivery mechanism is implemented to a message flow that is synchronous the client would be waiting for a response from the ESB until the message times out. To accommodate synchronous clients in a guaranteed delivery scenario, it is possible for the ESB to respond to the client with a fault message in case the message is not delivered and stored for later delivery. The following diagram depicts the message flow of the guaranteed delivery scenario with client acknowledgement using the WSO2 ESB.


  1. Client sends the message to the ESB.
  2. ESB try to deliver the message to the backend system, and the message fails
  3. ESB stores the message in a message queue
  4. ESB sends a response back to the client (response can be customized as required)
  5. ESB picks the message from the queue and try to deliver the message to the backend system; ESB retry can be customized to retry a given number of attempts.

The following synapse configuration can be used to configure this scenario. The configuration includes a proxy service, message broker, message processor, sequences and endpoints required to create the required mediation flow. Please note that the configuration is based on storing messages in an ActiveMQ based message queue. Hence it is required to follow the steps mentioned in the following link [1] setting up ActiveMQ with WSO2 ESB. [1]

Restricting grant types for an application in WSO2 API Manager

WSO2 API Manager has the capability of restricting which grant types are enabled to a given application. This functionality is provided via the management console of the API Manager. Given below are the steps required

1. App developers should have the required permission in order to restrict the grant types available for an application. Permission given below should be set to a user role associate to the App developer.

2. Once this is done please log out and log into the API Manager’s admin console

3. Now you would see the OAuth URL available in the left navigation, click on this.

4. Here you would see all the applications that are created by the App developer, from this menu select the relevant application to which the grant types should be restricted.

5. Once you are inside the selected application you can define which grant types should be allowed to a given application. By default all grant types are ‘un-checked’ and all grant types are allowed. If you want to override this default configuration select on the required grant types that should be allowed to a given application.

6. Once you are done click on the update button and the configuration would be updated.

IP based filtering for Proxy services exposed by WSO2 ESB

WSO2 ESB provides the ability to filter messages based on different parameters. These parameters include data in the message header, message content or even data relating to the message sender. This blog looks into how WSO2 ESB can be used to filter a message based on the IP Address of a client. The below ESB configuration would filter a message and send it to the beackend service only if it arrives from a pre-defined IP address range (192.168.1.*). If the message is recieved from any other IP address the message is dropped. This type of IP based filtering can be applied to secure a backend service from unauthorized access.