Currently* WSO2 Identity Server provides SOAP APIs for most of its functionalities. But if you want to access them in RESTful manner, no worries its just couple of things to needed to be done to expose them as REST APIs.

There can be several ways to do this but here we are going to do that by fronting SOAP service from a REST proxy using WSO2 ESB.  This pattern not only limited to WSO2 Identity Server, you could use same for any WSO2 Product.

Before we start, you need to download WSO2 Identity Server and WSO2 ESB. Here we are using WSO2 Identity Server 4.6.0 and WSO2 ESB 4.8.1.

Lets say you wanted to use some functionality of WSO2 Identity Server such as authentication using a REST API. First you need to find the relevant SOAP service, for the Authentication we are going to use “AuthenticationAdmin” service.

There are only 3 steps to whole process.

1. “The Easiest” : Start WSO2 Identity Server. 

Since we are going to start two WSO2 servers on same machine it will make a conflict on ports by two servers. So we are going to set port offset to 1 in WSO2 Identity Server. Open <IS_HOME>/repository/conf/carbon.xml file and search for tag “Offset” and set it to 1 as , <Offset>1</Offset>.

And also its better to search for the tag “HideAdminServiceWSDLs” and set it value to false as, <HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>.  By default WSO2 servers doesn’t publish wsdls and later in this post we’ll find it’s easier to generate message content if we have the wsdl.

Save the changes in carbon.xml and goto <IS_HOME>/bin/ directory and start WSO2 Identity Server by running wso2server.sh (for linux) or wso2server.bat (for windows).

2. “The Brain” : Start WSO2 ESB and create the Proxy which do the thing

Since we take care of the conflicts running two WSO2 servers in single machine in the step 1, we can start the ESB staright away by running wso2server.sh (for linux) or wso2server.bat (for windows) in <ESB_HOME>/bin/ directory.

Now we have to create proxy service which fronts our SOAP service in RESTful manner. Goto ESB management console, in the “Main” tab click on (“Services” -> “Add” ->) “Proxy Service”. Click on “Custom Proxy”, and then click on the link “switch to source view” on the top of the pane. It will switch you to source view of the proxy, now replace the generated content by copying below proxy and click on Save.

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="AuthenticationAdminProxy"
       transports="https"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
      <inSequence>
         <header name="Action" expression="get-property('transport', 'Action')"/>
      </inSequence>
      <outSequence>
         <send/>
      </outSequence>
      <endpoint>
         <address uri="https://localhost:9444/services/AuthenticationAdmin.AuthenticationAdminHttpsSoap11Endpoint/"
                  format="soap11"/>
      </endpoint>
   </target>
   <description/>
</proxy>

There are only four things to notice in this proxy.

i. The name of the proxy : This is defined in under the “name” attribute of the proxy and we have given the name “AuthenticationAdminProxy” which will be needed for step3.

ii. Transports of the proxy : The “transport” attribute of the proxy defines allowed transports for a proxy. Here we have allowed only “https” transport since this proxy handles sensitive info.

iii. Header mediator : To invoke backend SOAP service it is required to include the header “SOAPAction“. To do so we have added this header mediator which pick the value from the header “Action” of incoming request to the proxy and set it as the value of “SOAPAction” header.

iv. Endpoint address : This where we define the address of the backend SOAP service. In the endpoint address port number 9444 is used since we have started the WSO2 Identity Server with a port offset 1.

That’s all for ESB configuration. Next we are on to the last step.

3. “The Show” : Just run the curl

Now we have left to do is try out what we have built. You can use following CURL command to call our proxy which have the endpoint URL “https://localhost:8243/services/AuthenticationAdminProxy&#8221;. Note we have included the header “Action” which will be used as described in step 2-iii.

curl -k -H 'Content-Type: application/xml; charset=UTF-8' -H 'Action:"urn:login"' -d 'adminadmin' "https://localhost:8243/services/AuthenticationAdminProxy"

Since we have sent the valide credentials it will returns a response like following,

<ns:loginResponse xmlns:ns="http://authentication.services.core.carbon.wso2.org"><ns:return>true</ns:return></ns:loginResponse>

To generate the body of the curl request i have used soap ui, and this is where you find the benefit of making wsdls visible. You can try the same for any service, only you have to do is create the proxy and make the request with correct parameters.

Before the finishing things off, i thought to share the proxy which i used to debug things while writing this post. It almost the same as the above proxy addition to couple of logs. You also may find it useful if you go deeper.

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="AuthenticationAdminProxy"
       transports="https"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
      <inSequence>
         <log level="full"/>
         <log level="custom">
            <property name="Lang" expression="get-property('transport', 'Action')"/>
         </log>
         <header name="Action" expression="get-property('transport', 'Action')"/>
         <log level="full"/>
      </inSequence>
      <outSequence>
         <log level="full"/>
         <send/>
         <log level="full"/>
      </outSequence>
      <endpoint>
         <address uri="https://localhost:9444/services/AuthenticationAdmin.AuthenticationAdminHttpsSoap11Endpoint/"
                  format="soap11"/>
      </endpoint>
   </target>
   <description/>
</proxy>

That’s all… Peace of cake.. Isnt it?

(* With the upcoming revolutionary Carbon 5 platform, all the WSO2 products will comes with FULL REST support in OOB.)

ref : http://docs.wso2.org/display/ESB481/Using+REST+with+a+Proxy+Service