Exposing a non-secured service with security using ESB
- Heshan Suriyaarachchi
- Software Engineer - WSO2
Scenario
Lets assume following scenario for this tutorial.
1. You have a service running.
2. This service is exposed without any security.
3. As per a new requirement, you need to expose this service in a secured manner and you want to log requests coming into this service as well.
4. We do not have any control over service implementation.
Solution Criteria
Since the user can not modify the service, we need to have a proxy for the service. Then securtiy and logging capabilities are added to this proxy service.
The requests coming into the proxy service are passed to actual service implementation after going through security check & logging phases. The clients will be moidified to call the proxy service EPR instead. Following steps will show how to perform this using WSO2 ESB 2.1.1 .
STEPS
Setting up ESB
1) Download a distribution of the WSO2 ESB [1].
ie. wso2esb-2.1.1.zip
2) Extract the zip file. The folder created (wso2esb-2.1.1) will be referred as ESB_HOME.
3) Go to the ESB_HOME/samples/axis2Server/src/SimpleStockQuoteService directory. Run "ant" to build the service. A service archive will be created at ESB_HOME/samples/axis2Server/repository/services. The generated service archive can be deployed at an Axis2 server.
eg. SimpleStockQuoteService.aar
Assumption: It is assumed that the SimpleStockQuoteService's url is https://localhost:9763/services/SimpleStockQuoteService.
4) Go to the ESB_HOME/bin and run the script which starts wso2server.
eg. wso2server.bat for windows environments
wso2server.sh for linux environments
5) Then the server will be started. You can access the management console using the following URL [2].
6) Log into the Mangement Console using following credentials.
username: admin
password: admin
Enabling Security
7) Copy the attached StockQuoteSecClient.java to ESB_HOME/samples/axis2Client/src/samples/userguide/ folder. Then copy the attached policy file chb_policy_1.xml to ESB_HOME/repository/samples/resources/policy/ folder. Copy the following entry to the build.xml of ESB_HOME/samples/axis2Client.
NOTE: All the above mentioned configuration files and java source files are in the attached source.zip.
<target name="secstockquote" depends="compile">
<java classname="samples.userguide.StockQuoteSecClient"
classpathref="javac.classpath" fork="true">
<sysproperty key="symbol" value="${symbol}"/>
<sysproperty key="mode" value="${mode}"/>
<sysproperty key="addurl" value="${addurl}"/>
<sysproperty key="trpurl" value="${trpurl}"/>
<sysproperty key="prxurl" value="${prxurl}"/>
<sysproperty key="repository" value="${repository}"/>
<sysproperty key="policy" value="${policy}"/>
<sysproperty key="rest" value="${rest}"/>
<sysproperty key="wsrm" value="${wsrm}"/>
<sysproperty key="itr" value="${itr}"/>
<sysproperty key="uid" value="${uid}"/>
<sysproperty key="pwd" value="${pwd}"/>
<sysproperty key="javax.net.ssl.trustStore" value="./../../resources/security/client-truststore.jks"/>
<sysproperty key="javax.net.ssl.trustStorePassword" value="wso2carbon"/>
<sysproperty key="java.io.tmpdir" value="./../../work/temp/sampleClient"/>
<sysproperty key="java.endorsed.dirs" value="./../../lib/endorsed"/>
<!--
<jvmarg value="-Xdebug"/>
<jvmarg value="-Xnoagent"/>
<jvmarg value="-Djava.compiler=none"/>
<jvmarg value="-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000"/>
-->
</java>
</target>
The StockQuoteSecClient is the secure client that is used to call the service. The policy file contains the securtiy information needed for the Username Token authorization.
8) Go to the the left menu pane of the management console and click on Synapse (which is under configure tab). Replace the content of the attached synapse-configuration.xml there and click the update/save button.
Figure 1: Saving the Synapse configuration.
Then a proxy named SimpleProxy is created. Security and logging is enabled for this proxy service.
<?xml version="1.0" encoding="UTF-8"?>
<syn:definitions xmlns:syn="http://ws.apache.org/ns/synapse">
<syn:registry provider="org.wso2.carbon.mediation.registry.WSO2Registry">
<syn:parameter name="cachableDuration">15000</syn:parameter>
</syn:registry>
<syn:proxy name="SimpleProxy" transports="https http" startOnLoad="true" trace="disable">
<syn:target>
<syn:endpoint>
<syn:address uri="https://localhost:9763/services/SimpleStockQuoteService"/>
</syn:endpoint>
<syn:inSequence>
<syn:log level="custom">
<syn:property name="To" expression="get-property('To')"/>
<syn:property name="Action" expression="get-property('Action')"/>
<syn:property name="MessageID" expression="get-property('MessageID')"/>
<syn:property name="Reply-To" expression="get-property('Reply-To')"/>
<syn:property xmlns:soapEnv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" name="UserName" expression="//soapEnv:Envelope/soapEnv:Header/wsse:Security/wsse:UsernameToken/wsse:Username"/>
<syn:property xmlns:soapEnv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" name="Password" expression="//soapEnv:Envelope/soapEnv:Header/wsse:Security/wsse:UsernameToken/wsse:Password"/>
</syn:log>
<syn:header xmlns:wsse="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" name="wsse:Security" action="remove"/>
</syn:inSequence>
</syn:target>
</syn:proxy>
</syn:definitions>
The same proxy service can be created using the GUI of the Managemnet Console. Username token authentication can be applied to the above mentioned service via the Management Console as well.
Figure 2: Applying Security for the service.
Enabling Logging via log mediator
Above mentioned synapse-configuration enables logging of messages. The messages in the in-sequence is logged and the log level assigned is custom. In the Custom log level, the information wanted is extracted from the message and logged in.
<syn:inSequence>
<syn:log level="custom">
<syn:property name="To" expression="get-property('To')"/>
<syn:property name="Action" expression="get-property('Action')"/>
<syn:property name="MessageID" expression="get-property('MessageID')"/>
<syn:property name="Reply-To" expression="get-property('Reply-To')"/>
<syn:property xmlns:soapEnv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" name="UserName" expression="//soapEnv:Envelope/soapEnv:Header/wsse:Security/wsse:UsernameToken/wsse:Username"/>
<syn:property xmlns:soapEnv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" name="Password" expression="//soapEnv:Envelope/soapEnv:Header/wsse:Security/wsse:UsernameToken/wsse:Password"/>
</syn:log>
<syn:header xmlns:wsse="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" name="wsse:Security" action="remove"/>
</syn:inSequence>
Logging can be enabled through the GUI of the Managemnet Console.
Figure 3: Applying logging mediation to the service.
Invoking the service through the secure Proxy
9) Go to the folder ESB_HOME/samples/axis2Client. Then invoke the SimpleStockQuoteService using the StockQuoteSecClient by giving the following command.
eg. ant secstockquote -Daddurl=https://localhost:8243/services/SimpleProxy -Duid=[user id] -Dpwd=[password]
Assumption: SimpleProxy's url is https://localhost:8243/services/SimpleProxy
10) If you need to try this scenario out with an unsecured service of your preference; just replace the syn:address element's uri attribute with the End Point Referance(EPR) of the service that you want to invoke.
Additional Help
ESB documentation - https://wso2.org/project/esb/java/2.1.1/docs/index.html
ESB features - https://wso2.org/projects/esb/java/features
Mailing lists - https://wso2.org/mail
Library - https://wso2.org/library/esb
References
[1] - https://wso2.org/downloads/esb
[2] - https://<host>:<port>/carbon/
Author
Heshan Suriyaarachchi, Software Engineer, WSO2 Inc. heshan at wso2 dot com