Monday, September 16, 2013

Securing a Proxy Service in WSO2 ESB using a Username and passwordDigest (Hashpassword)

In this post i am going to explain how to secure a simple proxy service in WSO2 ESB 4.7.0 to be authenticated with UsernameToken method with using the username and hashpassword.

The HashPassword or NoPassword options are defined with WS-Policy 1.2 specification onwards. Therefore in order to have this feature we need to write a policy file using WS-Policy 1.2 spec.

First let's create a simple pass through proxy and make it secured.

1. Add a new pass through proxy  and specify an endpoint of a running service there. I have used SimpleStockQuoteService which can be run in <ESB_Home>/samples/axis2Server/src/SimpleStockQuoteService. Build the service using 'ant' and start the Axis2 server by,

cd ESB_home/samples/axis2Server $ sh 

2. After this go to the list of service in the UI. You will see that 'StockQuoteSecure' service is displayed as "Unsecured". Click on this link and it will redirect to a page where you can enable security to this service. Enable security there and select UsernameToken as the basic authentication mechanism as shown in the image below. After that goto next page and select the user groups who can access this service.

3. Once you finish this, WSO2 ESB admin console will display the service as secured, and we can only invoke this service using https:// endpoint now.
4. Next we need to change a default UsernameToken policy of the service and make it able to validate Hashpasswords. Goto the service dashboard of the secured service by clicking on it. Under the 'Quality of Service Configuration' section 'Policies' will be defined.
5. When you click on 'Policies' link it will be redirected to edit the current policy. Find 'StockQuoteSecureSoap11Binding' tab in here and click on 'Edit Policy' button as shown below.

6. Now let's define our new policy here. Copy the Following policy configuration and replace the existing policy definition with this one.
Save the policy back.


7. The StockQuoteSecure service is secured now and is configured to use Username and Hashpassword for authentication.
8. As defined in the policy configuration, it uses org.wso2.carbon.digestpwd.PWCBHandler class to validate the user. Here i have written class which can validate the default 'admin' user of WSO2 ESB.  Before trying to invoke the proxy service we need to add this PWCBHandler-1.0.jar client library into <ESB_Home>/repository/components/lib directory. You can download the jar from here.
[ The above sample PWCBHandler class is written to validate the 'admin' user only. According to your requirements you can write a customized PasswordCallBackHandler class which validates a set of registered users etc. in similar manner. ]
9. Now we can invoke the secured service using a Client, and i have used SOAP UI as the sample client here. Create a new SoapUI project by using SimpleStockQuoteService.wsdl file attached here. Then use any of the operations defined in the SimpleStockQuoteService and send a request to oure secured proxy service using SoapUI. Before sending the request enter the following values as Request Properties.

Username: admin
Password: admin
WSS-Password Type: PasswordDigest
WSS Time to Live: 2000

10. Once sent the request there will be a response message  returned from SimpleStockQuoteService which implies that the Usename/Hashpassword combination is authenticated successfully.


  1. Where is the SimpleStockQuoteService.wsdl file mentioned as "attached here" in step 9?

  2. What could cause this error message for this secure proxy example? How to fix it?

    [2013-10-23 18:39:50,435] ERROR - NativeWorkerPool Uncaught exception
    java.lang.RuntimeException: Undefined 'Security policy namespace cannot be null.' resource property
    at org.apache.rampart.RampartException.getMessage(
    at org.apache.rampart.RampartException.(
    at org.apache.rampart.RampartException.(
    at org.apache.rampart.RampartMessageData.setWSSecurityVersions(
    at org.apache.rampart.RampartMessageData.(
    at org.apache.rampart.RampartEngine.process(
    at org.apache.rampart.handler.RampartReceiver.invoke(
    at org.apache.axis2.engine.Phase.invokeHandler(
    at org.apache.axis2.engine.Phase.invoke(
    at org.apache.axis2.engine.AxisEngine.invoke(
    at org.apache.axis2.engine.AxisEngine.receive(
    at org.apache.synapse.transport.passthru.ServerWorker.processEntityEnclosingRequest(
    at org.apache.axis2.transport.base.threads.NativeWorkerPool$
    at java.util.concurrent.ThreadPoolExecutor.runWorker(
    at java.util.concurrent.ThreadPoolExecutor$

  3. Hi,

    i think you have attempted on creating a secure proxy. you have to create a custom proxy and the turn security on in this method

  4. Hi

    Im getting an error :

    The security token could not be authenticated or authorized

    when trying to invole the service from soap ui.

    any idea why this is happening??

    1. Hi Awanthika,

      With the attached handler you can only use admin/admin credentials to call the secure proxy. Can you please check whether you have used a different username/password combination in order to get this error?

  5. Can you explain why we need to replace the default policy with above mention policy in your post. I could send the request and get the response with SOAP UI without changing the policy.

    And also, I didn't include the PWCBHandler jar file to the ESB, and without that alse, ESB validating the users. It's only allows admin to send the request, since I configured only admin can send the request.

  6. Please look on this
    any help much appreciated

  7. Hello Isha! Great article, thanks!
    One question for you: I have already secured my service and successfully invoked it from SOAP UI. But now I need to invoke it from another WSO2 service. How can I accomplish that?

    Thank you very much!