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.
Parameter
Description
action
Contains the security action. The valid value is "usernameToken" which directs the handler to insert a token into the SOAP request.
user
Contains the user name.
passwordType
Contains the encoding type of the password. The valid value is "PasswordDigest". "PasswordDigest" sends the password in digest mode.
mustUnderstand
Must be set to false. It indicates that the security header inserted in the SOAP request is not a mandatory SOAP header and that it doesn't need to be understood by the Web service server.
password
Contains the Base64-encoded SHA-1 password. Use the WS-Security Password Helper to translate your plain text password into the proper format.
How to use
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.
Download the Apache WSS4J libraries v 1.1.0 from the Apache WSS4J Web site .
Copy WSS4J.jar to your Axis WEB-INF/lib directory.
You can overwrite the jar file if it already exists.
Download opensaml-1.1.jar from the OpenSAML Web site and copy to your Axis WEB-INF/lib.
Set up your CLASSPATH variables for the WSS4J implementation as follows.
SET JAVA_HOME=<Path to java base directory>
SET CATALINA_HOME=<Path to Tomcat base directory>
SET AXIS_HOME=<Path to Axis 1.2 base directory>
SET XERCES_HOME=<Path to Xerces base directory>
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%;
Restart Apache Tomcat.
You do not need to restart Tomcat if you have automatic deployment/class loading turned on.
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.
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>
See WSDoAllSender parameters for descriptions of the parameters.
Save the deployment descriptor (client-config.wsdd) to any location on your computer (running Tomcat).
Set the following property for the jvm used by Tomcat (5.5.12) and restart Tomcat.
-Daxis.ClientConfigFile=<path of the client-config.wsdd>
Double-click Apache Procrun Service Manager(Tomcat5w.exe) located in the <Tomcat_Home>\bin directory.
Click Java tab > Java Options of Apache Tomcat Properties dialog.
Restart Tomcat.
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>
Troubleshoot any exceptions.
The most common reason for exceptions is improperly set CLASSPATH variables. See Step 5 for the CLASSPATH variable settings related to WSS4J.
See the Apache Wiki site for more troubleshooting information.