Pages

Wednesday, March 28, 2007

Given below is a tutorial to use axis2 in implementing web services with security(This shows sync/Blocking call client along with Rampart security). This tutorial extends the previous tutorials to add security features to the web services using rampart module. For more details regarding any aspect of the tutorial, the axis2 or rampart documents will assist you.

Step 1: Extract the rampart-1.1.zip. Before doing anything more copy the %AXIS2_HOME%/lib to %AXIS2_HOME%/lib.1. Run the ant task on build.xml present in extracted folder. Now rebuild the whole axis2(i.e run the ant task in %AXIS2_HOME%/webapp). Deploy this in your server. Rename the lib to lib.2, and lib.1 to lib.[This is to run WSDL2JAVA and JAVA2WSDL tool, other wise the tools doesn't run and the reason is that the path AXIS2_CLASS_PATH becomes too long(I am running on Win 2000)]

Step 2: Create your service interface and impl class. Generate the WSDL using java2wsdl, generate the skeleton and stubs using wsdl2java, code the skeleton. Build the "MyRampartService.aar" and deploy on the server. Test the service. Use the client service stub to code a basic client, run the client to see its working. This step has set up a web service and a client in a usable state. Next, step goes through the rampart part.The service and skeleton are given below for reference.--------------Interface-------------------package axis2.adb.sync.rampart;public interface MyRampartService {public String getSecretText(String codeword);}

Step 3: This step uses the example from the rampart sample05. The intention is to encrypt the data in XML's which are exchanged between the client and the server. Copy %AXIS2_HOME%/repository to a convenient location. Copy %AXIS2_HOME%/conf/axis2.xml to %COPIED_LOCATION%/repository/modules/client.axis2.xml. Copy the rampart-1.1/samples/Keys to "resources" directory created on running the WSDL2JAVA on previous step. We will be using the same keystore which rampart has provided for encrypting the message. you use the "keytool" that is a part of JDK to create your own keystore. Add the rampart lib also to your classpath to compile and run the client. Copy from the sample05 directory org/apache/rampart/samples/sample05/PWCBHandler.java into your source directory(remember to change the package in PWCBHandler.java, if you put it in some other package). This is the callback handler that is called on the client and the server side for verifying the password.

Now, parameter OutFlowSecurity represents the action to be taken on the outgoing XML's. In our case it is to encrypt. The encryption property file client.properties is present in keys directory. It gives the details of the keystore file, the password to that keystore, the keystore type and the provider.

The parameter InFlowSecurity represents the action to be taken on the incoming XML's. It provides with the decryption property file which is same as the encryption property file in client.axis2.xml, the action item is same as the OutFlowSecurity action item and the password callbackhandler class. I am using the one which came with samples provided with apache rampart.Its given below.

Run ant command on this build.xml and deploy the service on axis2 in tomcat. Do not forget to restart the tomcat server if hotupdate is off.

Step 7: Edit the client and run. The client code is given below with appropriate comments. We do not have to configure the client using the XML, it can be done through code also. The below client uses the code when useRampartThroughCode is set to true. Please note that when this is used you do not have to configure the inflowsecurity and outflow security in the client.axis2.xml. Add the "resource/keys" on to the classpath before you run the client.

OutflowConfiguration ofc = new OutflowConfiguration(); //set the action item ofc.setActionItems("Encrypt"); //set the encryption user ofc.setEncryptionUser("service"); //set the property file; remember if the properties is not in classpath then it will not find this. ofc.setEncryptionPropFile("client.properties"); // return the Parameter return ofc.getProperty(); }

private static Parameter getInflowConfiguration() { InflowConfiguration ifc = new InflowConfiguration(); //set the action item ifc.setActionItems("Encrypt"); //set the password callback class ifc.setPasswordCallbackClass("axis2.adb.sync.rampart.callbackhandler.PWCBHandler"); //set the property file; remember if the properties is not in classpath then it will not find this. ifc.setDecryptionPropFile("client.properties"); //return the parameter return ifc.getProperty(); }

}

Step 8: The output.You will see the output:

Return Text: You have done a good choice to build an application

You can use the tcpmon tool to capture the XML exchanges. Then, you can observe the encrypted contents of the request and response messages.

NOTE: I am using the keystore's and the password callback handlers provided with rampart distribution for explaining this tutorial.