How to convert HTTP Basic Authentication to WS-Security Username Token?

Problem

Web Service Clients send user name/password via HTTP Basic Authentication but the Web service is secured using Username Token (WS-Security) and you don't have any control over the Web service. How to convert HTTP Basic Authentication to WS-Security Username Token?

Pre requisites

• Apache Ant 1.x
• Java 1.5.x or later

Applies To

• Applies to WSO2 Enterprise Service Bus version 2.1.x or later

Solution

If you are not familiar with WSO2 Enterprise Service Bus, for more information about WSO2 Enterprise Service Bus please check the project page here. We will refer to the folder where WSO2 Enterprise Service Bus is installed as <esb-home> in the rest of this "how to" article. We will be using WSO2 Enterprise Service Bus between the client and the Web service to convert basic authentication sent by the client to Username Token before forwarding the request to the Web service. We will use a sample service and a client in this tutorial to demonstrate the functionality.

The steps are as follows:

1. Download the resource pack of this tutorial from here and unzip it.
2. Copy the StockQuoteClient.java into <esb-home>/samples/axis2Client/src/samples/userguide/. Backup the existing version of StockQuoteClient.java as you might need it later for other purposes.
3. Copy the synapse_sample_700.xml into <esb-home>/repository/samples/ directory.
4. Copy the org.wso2.carbon.esb.mediator.basicauth-2.0.0.jar into <esb-home>/webapps/ROOT/WEB-INF/plugins/server/ directory
5. Open the <esb-home>/webapps/ROOT/WEB-INF/eclipse/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info file and add the following line to the bottom. Make sure that it is in a single line.

org.wso2.carbon.esb.mediator.basicauth,2.0.0,file:plugins/org.wso2.carbon.esb.mediator.basicauth-2.0.0.jar,10,true

6. Start WSO2 Enterprise Service Bus as follows:

   Linux : sh wso2esb-samples.sh -sn 700 --cleanCache
   Windows : wso2esb-samples.bat -sn 700 --cleanCache

7. Copy the UTStockQuoteService.zip into the  <esb-home>/samples/axis2Server/src and unzip it. Run the ant command inside the <esb-home>/samples/axis2Server/src/UTStockQuoteService directory. This will create a sample UT enabled web service for the Apache Axis2 instance we are going to start in the next step.
8. Start the Apache Axis2 server by giving the following command in the <esb-home>/samples/axis2Server.

Linux : axis2server.sh
Windows : axis2server.bat

9. Check the sample service by visiting the url - https://localhost:9002/services/. You will see a faulty service since we haven't configured the mail transport but that is fine.
10. Run client by typing the following inside <esb-home>/samples/axis2Client/ folder.

ant stockquote -Daddurl=https://localhost:8280/services/StockQuoteProxy

Features

• The mediator org.wso2.carbon.esb.mediator.basicauth-2.0.0.jar is a generic implementation. It can be used to convert BasicAuth request sent by any WS-Client to Username Token by only changing the synapse.xml. When this mediator is deployed in the "inSequence" of the proxy service it will add a security header to the SOAPEnvelope and attach a new Username Token built from the user name/password sent in the HTTP basic authentication header.
• The mediator can operate in two modes. They are namely "CreateWSSecurityAndForward" and  "DoAuthenticationAtMediator". What we explained so far are "CreateWSSecurityAndForward" mode.
  • CreateWSSecurityAndForward Mode - The mediator simply builds the UserNameToken and forwards it to the service. The authentication happens at the service.
  • DoAuthenticationAtMediator Mode - Authentication is done at the mediator and only authenticated messages are forwarded to the service. HTTP status code "401 Unauthorized" when invalid username/password is provided. The mediator can authenticate any user visible to WSO2 Enterprise Service Bus. WSO2 Enterprise Service Bus can be configured to read users from LDAP/ActiveDirectory or any other RDBMS database. For further details about this, please refer the user guide available in context help of the product.
  • The mode can be dynamically set from the synapse.xml file as follows:

<syn:property name="MediatorBehavior" value="DoAuthenticationAtMediator"/> 

Author

Dimuthu Leelarathne, Technical Lead, WSO2 Inc. dimuthul at wso2 dot com