Open topic with navigation

T U T O R I A L

Using WS-Security with Axis (Java) v2006

This tutorial demonstrates how to use Web Services Security (WS-Security), defined by the Organization for the Advancement of Structured Information Standards (OASIS), with Apache Axis 1.3. Once you configure your Axis toolkit for WS-Security, WS-Security headers are automatically included in your SOAP requests.

The Apache Axis implementation of WS-Security, through the Apache WSS4J Java libraries, allows you to send authentication information in your request instead of relying on a preliminary request/response from ArcWeb Authentication Web Service. See the Apache WSS4J Web site for more information about the Apache implementation of WS-Security.

The first part of this tutorial explains the system requirements and the WSS4J parameters for Username Token security header in your ArcWeb Services requests. The second part of this tutorial provides step-by-step instructions for using these parameters in a request. It assumes you have Apache Axis 1.3 and JDK 1.5 running on Jakarta (Apache) Tomcat. This tutorial also assumes you have an active subscription to ArcWeb Services. See ArcWeb Services authentication for general information on the ArcWeb Services authentication process.

System requirements

You must have the following components on your system before sending requests to ArcWeb Services using WS-Security with Axis.

• Apache Axis 1.3 (Final)
• JDK 1.5
• Jakarta (Apache) Tomcat 5.5.12
• Apache WSS4J libraries 1.1.0
• Active subscription to ArcWeb Services

WSDoAllSender parameters

WSDoAllSender and WSDoAllReceiver are the main Axis handlers implemented in WSS4J library for creating and interpreting secure SOAP requests. The WSDoAllSender handler is contained on the client side and is used to add a security header to a request. The WSDoAllReciever handler, implemented on the server that will receive this request, validates the authentication information in the incoming request header.  

WSDoAllSender handler contains the following parameters.

How to use

1. Verify that Network Time Protocol (NTP) is enabled on your client system. NTP establishes a common clock for all systems connected to the Internet. Since the ArcWeb clock uses NTP, enabling NTP on your system helps prevent unexpected expired token errors.

For more information on how to use NTP to synchronize your system clock, see http://tf.nist.gov/service/pdf/win2000xp.pdf or http://www.akadia.com/services/ntp_synchronize.html.

2. Download the Apache WSS4J libraries v 1.1.0 from the Apache WSS4J Web site.

3. Copy WSS4J.jar to your Axis WEB-INF/lib directory.

You can overwrite the jar file if it already exists.

4. Download opensaml-1.1.jar from the OpenSAML Web site and copy to your Axis WEB-INF/lib.

5. Set up your CLASSPATH variables for the WSS4J implementation as follows.
1. SET JAVA_HOME=<Path to java base directory>
2. SET CATALINA_HOME=<Path to Tomcat base directory>
3. SET AXIS_HOME=<Path to Axis 1.2 base directory>
4. SET XERCES_HOME=<Path to Xerces base directory>
5. Set CLASSPATH= %AXIS_HOME%\lib\axis.jar;%AXIS_HOME%\lib\axis-ant.jar; %AXIS_HOME%\lib\axis-schema.jar; %AXIS_HOME%\lib\commons-discovery-0.2.jar;%AXIS_HOME%\lib\commons-logging-1.0.4.jar; %AXIS_HOME%\lib\jaxrpc.jar;%AXIS_HOME%\lib\log4j-1.2.8.jar;%AXIS_HOME%\lib\saaj.jar;%AXIS_HOME%\lib\wsdl4j-1.5.1.jar;%AXIS_HOME%\lib\wss4j.jar;%AXIS_HOME%\lib\xmlsec-1.2.97.jar; %XERCES_HOME%\xml-apis.jar; %XERCES_HOME%\resolver.jar; %XERCES_HOME%\xercesImpl.jar;%CATALINA_HOME%\common\lib\activation.jar;%CATALINA_HOME%\common\lib\mail.jar;%CATALINA_HOME%\common\lib\servlet-api.jar;%JAVA_HOME%\lib\tools.jar;.;%CLASSPATH%;
6. Restart Apache Tomcat.

You do not need to restart Tomcat if you have automatic deployment/class loading turned on.

7. Verify that XML Security (xmlsec-1.2.97.jar) is properly configured. Do this by opening the Axis happiness page in a Web browser (typically located at http://localhost:8080/axis) and seeing that XML Security is listed in "Optional Components". If it is not listed, then you should instead see a link to download the xmlsec-1.2.97.jar file. Download the .jar file and save it under %AXIS_HOME%\lib.

You are now ready to send SOAP requests with WS-Security headers. A successful SOAP request requires three steps: adding the deployment descriptor, creating a valid request to a specific ArcWeb service, and troubleshooting any exceptions.

8. Create a deployment descriptor (client-config.wsdd) to your SOAP request. For example:

<!-- Using the WSDoAllSender security handler in request flow -->
<deployment xmlns="http://xml.apache.org/axis/wsdd/"  xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
<transport name="http" pivot="java:org.apache.axis.transport.http.HTTPSender"/>
<globalConfiguration>
<requestFlow >
<handler type="java:org.apache.ws.axis.security.WSDoAllSender" >
<parameter name="action" value="UsernameToken"/>
<parameter name="user" value="<ArcWeb user name>"/>
<parameter name="passwordType" value="PasswordDigest"/>
<parameter name="password" value="<WS-Security password>"/>
<parameter name="mustUnderstand" value="false" />
</handler>
</requestFlow >
</globalConfiguration>
</deployment>

1. See WSDoAllSender parameters for descriptions of the parameters.
2. Save the deployment descriptor (client-config.wsdd) to any location on your computer (running Tomcat).

9. Set the following property for the jvm used by Tomcat (5.5.12) and restart Tomcat.

-Daxis.ClientConfigFile=<path of the client-config.wsdd>

1. Double-click Apache Procrun Service Manager(Tomcat5w.exe) located in the <Tomcat_Home>\bin directory.
2.  Click Java tab > Java Options of Apache Tomcat Properties dialog.  
3. Restart Tomcat.

10. Create a valid request to an ArcWeb service. See the tutorial Using Axis (Java) with ArcWeb Services for step-by-step instructions for creating requests to ArcWeb Services (skip the step about running WSDL2Java against the Authentication Web Service HTTPS WSDL url).

Now that you have configured Axis for WS-Security, you no longer need to request a token from ArcWeb Authentication Web Service. Instead, your requests to ArcWeb services include the required authentication information via the WS-Security header.

Below is an example of a request. Note that the timestamp information and username are not valid values so you cannot send this request as is.

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<wsa:Action>findPlace</wsa:Action>
<wsa:MessageID>uuid:99c89fad-9c84-4fde-adc1-b1d1b3e0e35b</wsa:MessageID>
<wsa:ReplyTo>
<wsa:Address>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.arcwebservices.com/services/v2006/PlaceFinder</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-ce4fb682-9726-49ce-93cd-6e17156fee07">
<wsu:Created>2005-12-02T21:38:34Z</wsu:Created>
<wsu:Expires>2005-12-02T21:43:34Z</wsu:Expires>
</wsu:Timestamp>
<wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="SecurityToken-d15f7571-38d5-4411-9160-184d4fbe36d7">
<wsse:Username>
<ArcWeb username>
</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">2dj7Kf8eOLRnlihYS/MeDXlhAzU=</wsse:Password>
<wsse:Nonce>SpOU0e+TITWqgej21qYelQ==</wsse:Nonce>
<wsu:Created>2005-12-02T21:38:34Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soap:Body>
<findPlace xmlns="http://www.arcwebservices.com/v2006">
<placeName>Redlands</placeName>
<placeFinderOptions>
<dataSource xmlns="">ArcWeb:ESRI.Gazetteer.World</dataSource>
<filterCountry xsi:nil="true" xmlns="" />
<filterExtent xsi:nil="true" xmlns="" />
<filterType xsi:nil="true" xmlns="" />
<resultSetRange xsi:nil="true" xmlns="" />
<searchType xsi:nil="true" xmlns="" />
</placeFinderOptions>
<token />
</findPlace>
</soap:Body>
</soap:Envelope>

11. Troubleshoot any exceptions.

1. The most common reason for exceptions is improperly set CLASSPATH variables. See Step 5 for the CLASSPATH variable settings related to WSS4J.
2. See the Apache Wiki site for more troubleshooting information.

Visit the Feedback page to give comments or suggestions about the ArcWeb Developer's Guide.

ArcWeb site | ArcWeb support | support.esri.com

Copyright © ESRI