Enabling SSL for Axis2 web services

I have always had the trouble of setting up SSL based communication for my web services. I searched internet and finally nailed down the correct solution. I presume that you have a Axis2 web service running on Apache Tomcat server.

Here is what I have used:

• JDK and JRE 1.6
• Apache Tomcat 7.0.8
• Axis2 WAR distribution 1.6.2 (or Axis2 stand alone distribution)

Step#1: Generate server keystore and certificate

/root/my_workspace> vi gencerts.sh

#!/bin/sh
KEYTOOL=$JAVA_HOME/bin/keytool
echo Generating the Server KeyStore in file server.keystore
# The value of CN should be the IP address or host name on which web application will be deployed. Avoid specifying 'localhost'
$KEYTOOL -genkey -alias tomcat-sv -dname "CN=localhost, OU=X, O=Y, L=Z, S=XY, C=YZ" -keyalg RSA -keypass changeit -storepass changeit -keystore server.keystore

echo Exporting the certificate from keystore to an external file server.cer
$KEYTOOL -export -alias tomcat-sv -storepass changeit -file server.cer -keystore server.keystore

echo Generating the Client KeyStore in file client.keystore
$KEYTOOL -genkey -alias tomcat-cl -dname "CN=Client, OU=X, O=Y, L=Z, S=XY, C=YZ" -keyalg RSA -keypass changeit -storepass changeit -keystore client.keystore

echo Exporting the certificate from keystore to external file client.cer
$KEYTOOL -export -alias tomcat-cl -storepass changeit -file client.cer -keystore client.keystore

echo Importing Client's certificate into Server's keystore
$KEYTOOL -import -v -trustcacerts -alias tomcat -file server.cer -keystore client.keystore -keypass changeit -storepass changeit

echo Importing Server's certificate into Client's keystore
$KEYTOOL -import -v -trustcacerts -alias tomcat -file client.cer -keystore server.keystore -keypass changeit -storepass changeit

/root/my_workspace> chmod +x gencerts.sh
/root/my_workspace> ./gencerts.sh

Note:

• You can also write the above script in a BAT file for Windows OS. You require client keystore if you want to write a java client to interact with the web service


• The certificates generated by the script above is for testing purposes only. The browser will report "The certificate cannot be trusted" since they are not certified trusted by a certification authority like Verisign. Free trusted certificates are provided by CAcert and StartSSL on registration

Step#2: Modify Tomcat server's default configuration

The value of environment variable CATALINA_HOME will be the Tomcat server installation directory. Edit  server.xml under $CATALINA_HOME/conf/ and make the below changes: 

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS"
    keystoreFile="/root/my_workspace/server.keystore"              keystorePass="changeit"/>

You can also add attributes with values for truststoreFile, truststoreType, truststorePass, keyAlias to the above tag.

Step#3: Modify web service's axis configuration

My web service WAR file is myws.war. When I deploy this file by placing it under $CATALINA_HOME/webapps/ directory, and start the server, I find axis2.xml is under $CATALINA_HOME/wepapps/myws/WEB-INF/conf/ directory. Edit this file as per instructions below:

1. Comment the existing default xml tag entry for http transportReceiver 
2. Add two entries as shown here:
   <transportReceiver name="http" class= "org.apache.axis2.transport.http.AxisServletListener">  
      <parameter name="port">8080</parameter>
   </transportReceiver>
   <transportReceiver name="https" class= "org.apache.axis2.transport.http.AxisServletListener">  
      <parameter name="port">8443</parameter>
   </transportReceiver>
   

   Note:
   

   • By default the port parameter is 8080 for transport receiver. If you want to have two transport receivers (e.g. http and https), then make sure to add ports in both tags as shown above
   
   
   • Without making changes to axis2.xml, if you try to access the web service using HTTPS, Internal Server Error is thrown in the browser. This is a common problem which me and many others faced. Arrgh!

3. Restart Tomcat server
4. Now my web service is accessible on URLs:
   https://<host-ip>:8443/myws/services/myService
   http://<host-ip>:8080/myws/services/myService

And there you go, everything is set. Let me know if you face anything unusual after following these steps.  So then, until next time, happy programming!

Further reading:
Apache Tomcat 7: SSL Configuration HOW-TO

Developing web services using Apache Axis2

I am going to present to all folks who are eager to develop web services using Apache Axis2. I am assuming that you guys have fair idea about what web service is, SOAP, structure of a valid WSDL, and all the basics about web services.

What I am about to tell you is if you have a valid WSDL document(xml) then it's quite easy to develop a web service out of it in simple steps. This is called the top down approach. Apache Axis2 distribution provides set commands that generates Java code when WSDL is given as input. The generated code is just a skeleton of the web service wherein you have fill it with your business logic.

Requirements:

• Eclipse IDE 3.4 or above
• Apache Axis2 (stand alone) 1.4 or above: Download releases
• A WSDL ( I am using CalcWSDLFile.wsdl)

In the axis distribution folder: ${AXIS2_HOME}/bin, you will find two script files: WSDL2Java.bat & Java2wsdl.bat. I will be using wsdl2Java.bat for since I am working on Windows and also because it's a top down approach. If you are working under Linux, there will be respective .sh files accordingly. 

My WSDL file: CalcWSDLFile.wsdl

This script (wsdl2java.bat) uses few options to generate code accordingly. Now, we are all set. Along with this, these steps will allow you to setup your development environment correctly.

1. Create a folder with name CalculatorWS. I have created it under C:\Amit\webservice\. This will be your workspace (project) folder in Eclipse. 

2. To generate server side code: Execute the below line:

wsdl2java.bat  -ss -g -u -sd -ssi -d adb -uri  C:\Amit\webservice\CalculatorWS\wsdl\CalcWSDLFile.wsdl  -o C:\Amit\webservice\CalculatorWS

-o: The path where the code is generated. The absolute path of folder: CalculatorWS

-uri: The path of of your WDSL file

The command should execute without throwing any error. To know more about rest of the script options mentioned above, have a look at the reference. 

3. Copy the lib folder under ${AXIS2_HOME} to C:\Amit\webservice\CalculatorWS\

i.e. the absolute path of lib will look like: C:\Amit\webservice\CalculatorWS\lib

4. Open Eclipse. File -> New -> Java Project. Now, provide project name. In the Contents frame, select “Create project from existing source” and provide the path of folder: C:\Amit\webservice\CalculatorWS. Click Finish. Your Eclipse work space is now setup successfully.

Look of my workspace: CalculatorWS

5. Now, next thing is to fill the generated with business logic. As highlighted in the screenshot, there will be a source file with the name: {service-name}Skeleton.java. {service-name} is got from the WSDL. This is the file where you come in, process the request, do some logic and reply with a response. 

Deployment

Once you are done with your development, it's time for deployment.

1. Create a folder named CalculatorWS under ${AXIS2_HOME}\repository\services. Then create a folder with name under META-INF under ${AXIS2_HOME}\repository\services\CalculatorWS

2. Copy all the files under C:\Amit\webservice\CalculatorWS\resources to ${AXIS2_HOME}\repository\services\CalculatorWS\META-INF. This folder contains XSDs, WSDLs and other web service related XMLs.

3. Copy all the compiled class files along with packages from work space folder: C:\Amit\webservice\CalculatorWS\bin to ${AXIS2_HOME}\repository\services\CalculatorWS.

4. Your web service is now successfully deployed. Open command prompt, goto ${AXIS2_HOME}\bin

5. Run the command axis2server.bat. You will see that your service is being deployed successfully. From the browser, navigate to URL: http://{your-host-name}:{axis2-server-port-number}/axis2/services/. For example, in my case: http://localhost:8090/axis2/services/

Web service getting deployed successfully

A list of deployed web services is displayed. Click the hyper link of your web service, the WSDL is displayed. Look for the tag soap:address. The value of the attribute location is the URL for the clients to connect to this web service. SOAPUI is a good client to test your web service.

I hope people will find this post useful.