Malla

1. Overview

Apache AXIS2 is a core engine for developing web services and is a complete rewrite of widely used Apache AXIS (AXIS1) to allow more flexibility, efficiency, low memory foot print etc.  AXIS2 support several WS-* specifications , SOAP 1.x and various transport bindings including HTTP, JMS, TCP etc. In AXIS2, the web service artifacts are generated using various native data bindings such as ADB (Axis Data Binding), XMLBeans, JibX however it does also support JAX-WS style web services.

OpenSSO provides comprehensive solution for securing web services developed using various technologies and platforms. The WS-Security and WS-Trust are the core security specifications as part of WS-* specifications published via the OASIS Security Committee. The WS-Trust defines a Trust Authority popularly known as STS (Security Token Service) that issues security tokens (for e.g. SAML Tokens) for the consumption of web service clients and web service providers that would like to support WS-Security for their communication model.

OpenSSO Enterprise 8.0 supports Security Token Service (WS-Trust Service) on majority of the platforms including Sun Application Server( Glassfish), Sun Web Server 7.x, Web Logic, Websphere, Tomcat, Jboss, Oracle 10g Application Server, Geronimo. However, currently with 8.0, the WS-Security  for web service client (WSC) s is supported only on Glassfish.  For the web service provider (WSP) s, the road map is to support through OpenSSO Policy Agents 3.0.

This document describes in detail the WS-Security support for the web service clients and providers that are developed using AXIS2.


2. Installation Requirements

The following software is used to demonstrate the OpenSSO based WS-Security for the AXIS2 web service clients and as well for the web service providers.

1.Apache Tomcat 6.0.18
2.OpenSSO Zip
3.OpenSSO Web Services Security Agent
4.Apache AXIS2
5.Web Service Samples


3. OpenSSO WS-Security Integration Architecture with AXIS2

This tutorial does not describe in detail about AXIS2 core engine architecture, however, it assumes that user knows the basic concepts and components in AXIS2 Web Services. Also it uses AXIS2 instead of AXIS (AXIS1) for better support model even though the architecture does not change from the OpenSSO point of view. The AXIS2 core architecture consists of the following core components and non-core components.

Core components:

XML Object Model (AXIOM)
SOAP Processing Model : Handler framework
Information Processing Model: Contexts and descriptions.
Non core components:

Deployment Model
Transports
Client API
Code generation model

The core components are part of the AXIS2 core engine that handles the message flow and XML processing and the non core components help to generate the necessary artifacts. The main functionality of AXIS2 core is to process the incoming/out going message and deliver to the destined application. Axis2 has the concept called “flow”, where the flow is collection of “phases” and phase is a collection of handlers. The handlers can be used to process the incoming or outgoing SOAP messages depending on the InFlow or OutFlow configurations. These are configured through axis2.xml which is the key configuration XML file for the AXIS2.

 Fig 1. OpenSSO WS-Security Integration for AXIS2 web services

In this architecture, there are two levels of integrations that are done to secure and validate web service communications.

The first integration for WSCs is to obtain the authenticated user context from the OpenSSO into the web service client application. Alternatively one could use OpenSSO Policy Agent, however this integration takes the simplistic approach through J2EE filter. This filter not only authenticates the user but exposes the authenticated user context to the SOAP layer via the Thread Local.   

The second integration is to intercept the outgoing SOAP message from a web service client application via the handler in the “Security” phase and secure them using OpenSSO SDK.

For the web service provider applications (WSPs), the openSSO based handler in the Security phase  intercepts and validates the incoming SOAP request, and then authenticates against OpenSSO to generate the authentication context (session).


4. Deployment of OpenSSO

This tutorial uses OpenSSO on tomcat 6.0.18 platform, even though you could use any supported platform. Download the opensso.zip as mentioned in section 2, and follow the OpenSSO Installation and Configuration Guide as mentioned here.

After successful installation and configuration, make sure that OpenSSO instance is accessible by login into the OpenSSO Administration Console.

Note: The web service samples developed below assumes the localhost and port 8080 for the container that the OpenSSO is deployed.

5. Developing Web Service Provider and Web Service Clients using AXIS2.

In this tutorial, we describe step-by-step development of web service applications using AXIS2 and integrate with OpenSSO ClientSDK.

Note: The steps below uses macros liberally,  for e.g. $opensso_wssagents_dir for the WSS Agents directory, however, make sure you use the fullpath where ever the macros are referenced.

   5.1 Configure OpenSSO ClientSDK so that it can talk to the OpenSSO instance.

5.1.1 Download and unzip the openssowssproviders.zip to a staging area or e.g. /export/openssoagents. This directory will be referred as $opensso_wssagents_dir

5.1.2 cd  to the directory $opensso_wssagents_dir/resources and edit AMConfig.properties. The AMConfig.properties describes configuration properties that enables the OpenSSO ClientSDK to talk to the OpenSSO Server deployed on tomcat.

Edit for the folowing properties in AMConfig.properties:

com.iplanet.services.debug.level=message    //This helps in debugging for any failures
com.iplanet.services.debug.directory=<directory where debug files can be written>  // for e.g. /tmp/wss
com.iplanet.am.naming.url=http:<openssohost>:<openssoport>/<openssodeploydir>/namingservice
com.sun.identity.agents.app.username=amadmin
com.iplanet.am.service.password=<password for the amadmin>
com.encryption.pwd=<No setting i.e. empty, remove if any macro is present here>
com.iplanet.am.server.protocol=http
com.iplanet.am.server.host=<host where the OpenSSO is deployed> // for e.g. localhost
com.iplanet.am.server.port=<port where the OpenSSO is deployed> // for e.g. 8080
com.iplanet.am.services.deploymentDescriptor=<deployment uri> // for e.g. opensso
com.iplanet.am.cookie.name=iPlanetDirectoryPro
com.sun.identity.saml.xmlsig.keystore=<directory where the keystore.jks is localted>
                          // here it is $openssoagentsdir/resources/keystore.jks
com.sun.identity.saml.xmlsig.storepass=$openssoagentsdir/resources/.storepass
com.sun.identity.saml.xmlsig.keypass=$openssoagentsdir/resources/.keypass
com.sun.identity.saml.xmlsig.certalias=test
com.sun.identity.login.url=http://<openssohost>:<openssoport>/<deployuri>/UI/Login
com.sun.identity.liberty.authnsvc.url=http://<openssohost>:<openssoport>/<deployurl>/Liberty/authnsvc
com.sun.identity.wss.trustclient.enablemetro=false
com.sun.identity.wss.soapversion=1.1

Note: In the above configuration, we try to use the SOAP 1.1 version, so we have to make sure the OpenSSO STS supports SOAP 1.1 binding. This will be done in later sections.


    5.2 Generate and deploy StockService.war as a web service provider application in Tomcat

5.2.1 Download the AXIS2 standard binary distribution as mentioned in section 2. Unzip the AXIS2 zip file to your favorite folder. The binary distribution contains axis2 scripts to generate the web service artifacts and as well as a build script to generate the axis2 war file.

5.2 .2 Set the AXIS2_HOME environment variable to where the AXIS2 is installed. Also set JAVA_HOME to where the Java is installed. It requires atleast JDK1.5

5.2.3 Download and unzip the axis2-samples.zip to a staging directory. The staging directory will be referred as $axis2_samples_dir and contains files stockservice.wsdl and stock.xsd. The stockservice.wsdl describes a simple stock web service WSDL.

5.2.4 Generate the web service artifacts using wsdl2.sh
       $AXIS2_HOME/bin/wsdl2.sh  -uri file:$axis2_samples_dir/stockservice.wsdl -p com.sun.samples -o $axis2_samples_dir/stockservice -d adb -s -wv 1.4.1 -ss -sd

This command generates the web service artifacts under $axis2_samples_dir/stockservice directory and a build script to generate service ".aar" file.

5.2.5 Copy the $axis2_samples_dir/source/com/sun/samples/StockServiceSkeleton.java to $axis2_samples_dir/stockservice/src/com/sun/samples.
The StockServiceSkeleton.java provides the business logic for the Stock Service.

5.2.6 Copy the $axis2_samples_dir/source/com/sun/samples/ServerHandler.ava to $axis2_samples_dir/stockservice/src/com/sun/samples directory. This is handler class for validating incoming stock service requests.

5.2.7 Edit the generated build.xml in the directory $axis2_samples_dir/stockservice for the axis2.class.path as below.

       <fileset dir="<opensso wssagents directory>/lib">
            <include name="openssoclientsdk.jar"/>
        </fileset>
        <fileset dir="<tomcat installation directory>/lib">
            <include name="servlet-api.jar"/>
        </fileset>

5.2.8 Build the generated stubs for stock service now.
         cd $axis2_samples_dir/stockservice; ant -f build.xml
   If the build is successful, it generates the StockService.aar under build/lib directory.

5.2.9 Also, generate the jar file for handler class.
        cd $axis2_samples_dir/stockservice/build/classes; jar cvf handler.jar com/sun/samples/ServerHandler.class

5.2.10 Now, let's build and customize the axis2 war file to deploy with stock service.
      cd $AXIS2_HOME/webapp and generate axis2.war by executing ant -f build.xml
      The axis2.war is generated under $AXIS2_HOME/webapp/dist directory.

5.2.11 Create a directory named "war" under $axis2_samples_dir/stockservice and copy the axis2.war to $axis2_samples_dir/stockservice/war directory. Unwar the axis2.war using the command:
      jar -xvf axis2.war

5.2.12 Now copy all the built artifacts to create StockService.war file.
  cp $axis2_samples_dir/stockservice/build/classes/handler.jar  $axis2_samples_dir/stockservice/war/WEB-INF/lib

  cp $axis2_samples_dir/stockservice/build/dist/StockService.aar $axis2_samples_dir/stockservice/war/WEB-INF/services

cp $axis2_samples_dir/config/axis2-server.xml $axis2_samples_dir/stockservice/war/WEB-INF/conf/axis2.xml

The modified axis2.xml contains the configured handler for security for InFlow and OutFlow phases.

 cp $opensso_wssagents_dir/lib/openssoclientsdk.jar $axis2_samples_dir/stockservice/war/WEB-INF/lib


cp $opensso_wssagents_dir/resources/AMConfig.properties  
     $axis2_samples_dir/stockservice/war/WEB-INF/classes


5.2.13 Replace Apache AXIS2 SAAJ implementation with Sun's implementation.  The Apache's SAAJ implementation does not seem to be fully extendible from DOM as of release 1.4.2 and it had few issues.

cp $axis2_samples_dir/lib/saaj-api.jar $axis2_samples_dir/stockservice/war/WEB-INF/lib
cp $axis2_samples_dir/lib/saaj-impl.jar $axis2_samples_dir/stockservice/war/WEB-INF/lib
rm $axis2_samples_dir/stockservice/war/WEB-INF/lib/axis2-saaj-api-1.4.1.jar
rm $axis2_samples_dir/stockservice/war/WEB-INF/lib/axis2-saaj-1.4.1.jar

Note: Removal of Apache SAAJ jars are mandatory since the SAAJ API uses FactoryFinder to determine the implementation.

5.2.14 Generate StockService.war using the command:
   cd $axis2_samples_dir/stockservice/war
   jar cvf StockService.war *

5.2.15 Deploy the StockService.war by copying the war file into $tomcat-install-dir/webapps.

      5.3 Generate and deploy StockClient.war as a web service provider application in Tomcat

This step assumes that you have done 5.2.1, 5.2.2 and 5.2.3 if at all you are deploying from another machine or a shell.

5.3.1 Generate the web service client artifacts using the command:
$AXIS2_HOME/bin/wsdl2java.sh -uri file:$axis2_samples_dir/stockservice.wsdl -p com.sun.samples -o $axis2_samples_dir/stockclient -d adb -s

This command generates the stock service client artifacts under $axis2_samples_dir/stockclient and a build script to generate the client jar file.

5.3.2 Copy the client  java files to generated stockclient directory.
  cp $axis2_samples_dir/source/com/sun/samples/GetQuote.java $axis2_samples_dir/stockclient/src/com/sun/samples
  cp $axis2_samples_dir/source/com/sun/samples/ClientHandler.java $axis2_samples_dir/stockclient/src/com/sun/samples
  cp $axis2_samples_dir/stockclient/src/com/sun/samples $axis2_samples_dir/src/com/sun/samples

The source has GetQuote.java which extends from an HttpServlet and invokes a web service invocation to the StockService. Also it has a ClientHandler and the ClientFilter which enables the ws-security using OpenSSO.

Note: The servlet assumes the StockService is deployed at
  http://localhost:8080/StockService/services/StockService

However, customize this depending on your deployment.

5.3.3 Edit the $axis2_samples_dir/stockclient/build.xml to include the openssoclientsdk.jar and servlet-api.jar as below:

Add the following to axis2.class.path element (Note: use the complete paths for the jar files)

<fileset dir="$tomcat_install_dir/lib">
            <include name="servlet-api.jar"/>
        </fileset>
        <fileset dir="<opensso_agents_install_dir>/lib">
            <include name="openssoclientsdk.jar"/>
        </fileset>
 </fileset>

5.3.4 Build the client jar file using the command:
    cd $axis2_samples_dir/stockclient; ant -f build.xml

This command generates the StockService-test-client.jar under $axis2_samples_dir/build/lib.

5.3.5 cd $axis2_samples_dir/client/war

This  directory has a pre-configured web.xml and axis2.xml so that it can be built for StockClient.war.

The web.xml contains the filter, servlet configurations. axis2.xml contains the ClientHandler in the "Security" phase.

Now copy the necessary artifacts to build the client war file.

cp $opensso_wss_agents/lib/openssoclientsdk.jar $axis2_samples_dir/client/war/WEB-INF/lib
cp $opensso_wss_agents/resources/AMConfig.properties $axis_samples_dir/client/war/WEB-INF/classes
cp $axis2_samples_dir/stockclient/build/lib/StockService-test-client.jar $axis2_samples_dir/client/war/WEB-INF/lib
cp $axis2_samples_dir/lib/saaj-api.jar $axis2_samples_dir/client/war/WEB-INF/lib
cp $axis2_samples_dir/lib/saaj-impl.jar $axis2_samples_dir/client/war/WEB-INF/lib
cp $AXIS2_HOME/modules/* $axis2_samples_dir/client/war/WEB-INF/modules
cp $AXIS2_HOME/web-app/WEB-INF/classes/*.properties $axis2_samples_dir/client/war/WEB-INF/classes

5.3.6 Now build the client war using the command:
 cd $axis2_samples_dir/client/war; jar cvf StockClient.war *

5.3.7 Deploy the StockClient by copying the StockClient.war to $tomcat_install_dir/webapps


6. Running the StockQuote Sample


6.1 Login into the administration console of OpenSSO instance.
       http://<host>:<port>/opensso

6.2 After successful login, navigate to the WSC configuration page:
    Access Control -> Default Realm -> Agents -> Web Service Client
    Select "STSSecurity" as the security mechanism , and "SecurityTokenService" as the STSAgent.
    Also edit the STS endpoints are:
      http:<host>:<port>/opensso/sts/soap11
      http:<host>:<port>/opensso/sts/mexsoap11
    Here, we choose STS to show case the end user based SAML Assertion tokens from the
    OpenSSO SecurityTokenService (WS-Trust Service).


6.3 Access the Stock Client home page.
      http://<host>:<port>/StockClient/index.jsp

      This should redirect to the OpenSSO Login page for authentication.

6.4 Enter the user credentials (for e.g. demo/changeit)
      After successful login, it redirects back to the StockClient's index.jsp

6.5 Choose your favorite stock symbol for e.g. JAVA and Click "GetQuote"

6.6 If the web service invocation is successful, you should see the Stock Quote Values Display
      page. Verify the Stock Quote Request/Responses with SAML Tokens in tomcat's log file (catalina.out). The log file has SOAP messages before and after security.

6.7 You can choose to try out with various security mechanism combinations. For more details, check the OpenSSO documentation.