Configuring Web Services Security for the Tomcat 6.0 Version 3.0 Agent (Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Apache Tomcat 6.0)

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Apache Tomcat 6.0

Configuring Web Services Security for the Tomcat 6.0 Version 3.0 Agent

The Tomcat 6.0 version 3.0 agent supports Web Services Security for web service providers. A web service provider (WSP) deployed on Tomcat 6.0 protected by the agent can have additional security provided by the agent. For example, you can configure the Tomcat 6.0 version 3.0 agent and OpenSSO Enterprise server to support various Web Services Security profiles, including Username token, X509 token, and SAML2 token.

To Configure Web Services Security for the Tomcat 6.0 Agent

You must first download and install the JAX-WS JAR files from the JAX-WS Reference Implementation (RI) project.

Note About the Examples. The examples in this section use /opt as the download and installation directory. However, if you prefer, you can use a different directory. These examples are also intended for a Solaris or Linux system. If you are running on another platform such as Windows, you will need to make changes for the paths and filenames.

Download and unzip Tomcat 6.0 in /opt. For example: /opt/apache-tomcat-6.0.18

Download jaxws-ri.zip from the following site: https://jax-ws.dev.java.net/

Unzip jaxws-ri.zip, also in /opt.

On Solaris and Linux systems, set the JAX-WS RI shell scripts to be executable. For example:
```
cd /opt/jaxws-ri/bin
chmod +x *.sh
```

In /opt/jaxws-ri/tomcat.xml, modify the tomcat.home property for your deployment. For example:
```
<property name="tomcat.home" value="/opt/apache-tomcat-6.0.18"/>
```

Install the JAX-WS JAR files into Tomcat 6.0. For example, using ant:
```
/share/builds/components/ant/1.6.5/bin/ant -f tomcat.xml install
```

Configure and deploy your WSP application.

If you are deploying new web services that uses JAX-WS, see Configuring the StockService and StandAloneStockClient Samples as an example to follow for your web services.

If your application is already deployed and using WSS with JAX-WS, you might need only to add the agent filter in the web.xml file.

Install and configure the Tomcat 6.0 version 3.0 agent, as described in this guide.

Follow the general steps to configure the web service provider (WSP) and web service client (WSC) in Web Services Security Support for J2EE Agents in Policy Agent 3.0 in Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.

Deploy your WSP application into the Tomcat 6.0 web container. For example, to deploy the StockService.war sample:
```
cp /opt/wsp/samples/tomcat/StockService/dist/StockService.war 
/opt/apachetomcat-6.0.18/webapps/
```

Start the Tomcat 6.0 web container.

Configuring the `StockService` and `StandAloneStockClient` Samples

This section describes how to configure the Sun StockService sample as the WSP and the StandAloneStockClient as the WSC. Use these samples as models to configure your own WSS applications.

To Configure the `StockService` Sample

Create the wsp directory. For example, in /opt.

Download openssowssproviders.zip from the WSS Agent link on https://opensso.dev.java.net/public/use/index.html.

Unzip openssowssproviders.zip in /opt/wsp/.

Create the tomcat directory under /opt/wsp/samples for the Tomcat 6.0 files. For example:
```
cd /opt/wsp/samples
mkdir tomcat
```

Copy the GlassFish sample files to the new tomcat directory:

cp -r /opt/wsp/samples/glassfish/* /opt/wsp/samples/tomcat/

Rename glassfish.properties for Tomcat 6.0:

cd /opt/wsp/samples/tomcat/
mv glassfish.properties tomcat.properties

In /opt/wsp/samples/tomcat/tomcat.properties, remove the GlassFish properties and add the following:
```
wsp.home=/opt/wsp
jaxws.home=/opt/jaxws-ri
jaxws.lib.dir=/opt/jaxws-ri/lib
```

Edit /opt/wsp/samples/tomcat/StockService/build.xml as shown in the next example.

Tip –

To create a new Tomcat build.xml file, just copy the following XML statements.

<?xml version="1.0" encoding="UTF-8"?>
<project name="StockQuoteService" default="all" basedir=".">
  <description>Builds, tests, and runs the project stockclient.</description>
  <property file="../tomcat.properties"/>
  <condition property="wsimport-script-suffix" value=".bat">
    <os family="windows"/>
  </condition>
  <condition property="wsimport-script-suffix" value=".sh">
    <not>
      <os family="windows"/>
    </not>
  </condition>
  <path id="build.class.path">
    <pathelement location="build/classes"/>
    <fileset dir="${jaxws.lib.dir}">
      <include name="**/*.jar"/>
    </fileset>
  </path>
  <target name="-pre-compile">
    <mkdir dir="build/classes"/>
    <mkdir dir="web/WEB-INF/classes"/>
    <exec executable="${jaxws.home}/bin/wsimport${wsimport-script-suffix}">
    <arg line="-verbose -d build/classes web/WEB-INF/wsdl/StockService/stockservice.wsdl"/>
    </exec>
    <copy file="src/java/handlers.xml" todir="web/WEB-INF/classes"/>
  </target>
    <target name="compile" depends="-pre-compile">
    <javac fork="true" destdir="build/classes" srcdir="src/java">
    <classpath refid="build.class.path" />
    </javac>
  </target>
  <target name ="war" depends="compile">
    <mkdir dir="dist"/>
    <copy todir="web/WEB-INF/classes">
    <fileset dir="build/classes" />
    </copy>
    <war destfile="dist/StockService.war" webxml="web/WEB-INF/web.xml">
    <zipfileset dir="web" />
    </war>
  </target>
    <target name="all">
    <antcall target="war" />
  </target>
</project>

In the following file, change the references to localhost and port 8080, depending on your deployment:
```
/opt/wsp/samples/jboss/StockService/web/WEB-INF/wsdl/StockService/stockservice.wsdl
```

Remove /opt/wsp/samples/jboss/StockService/web/WEB-INF/sun-web.xml. For example:
```
cd /opt/wsp/samples/jboss/StockService/web/WEB-INF
rm sun-web.xml
```

In the same directory, create sun-jaxws.xml with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<endpoints
  xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime'
  version='2.0'>
  <endpoint
    name='StockService'
    implementation='com.samples.StockService'
    url-pattern='/StockService' />
</endpoints>

In the same directory, in web.xml, add the agent <filter>, <filter-mapping>, <listener>, <servlet>, and <servlet-mapping> entries, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">

  <filter>
    <filter-name>Agent</filter-name>
    <filter-class> com.sun.identity.agents.filter.AmAgentFilter </filter-class>
  </filter>
  <filter-mapping>
    <filter-name>Agent</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
   <dispatcher>INCLUDE</dispatcher>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>ERROR</dispatcher>
  </filter-mapping>

  <session-config>
    <session-timeout>
      30
    </session-timeout>
  </session-config>
  <welcome-file-list>
    <welcome-file>
      index.jsp
    </welcome-file>
  </welcome-file-list>

  <listener>
    <listener-class>
      com.sun.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>

  <servlet>
    <description>JAX-WS endpoint</description>
    <display-name>The JAX-WS servlet</display-name>
    <servlet-name>jaxws</servlet-name>
    <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>jaxws</servlet-name>
    <url-pattern>/StockService</url-pattern>
  </servlet-mapping>
</web-app>

Build the StockService WAR file. For example, using ant:

cd /opt/wsp/samples/jboss/StockService
/share/builds/components/ant/1.6.5/bin/ant -f build.xml

To Configure the `StandAloneStockClient` Sample

Change to the StandAloneStockClient directory:

cd /opt/wsp/samples/tomcat/StandAloneStockClient

In src/com/samples/SecuringWS.java, change any references to localhost and port 8080, depending on your deployment.

In the /opt/wss/samples/tomcat/StandAloneStockClient directory, modify build.xml for Tomcat 6.0 rather than GlassFish:

<?xml version="1.0" encoding="UTF-8"?>
<project name="StandAloneStockClient" default="default" basedir=".">
  <description>Builds, tests, and runs the project stockclient.</description>
  <property file="../tomcat.properties"/>
  <property name="is.java-client.module" value="true"/>
  <target name="default" depends="run"/>
  <target name="build" depends="clean">
    <mkdir dir="build/classes"/>
    <javac srcdir="src"
    destdir="build/classes"
    classpath="xyz.jar"
    debug="on">
    <classpath>
      <pathelement location="${wsp.home}/lib/openssowssproviders.jar"/>
      <pathelement location="${wsp.home}/lib/webservices-rt.jar"/>
      <pathelement location="${wsp.home}/lib/openssoclientsdk.jar"/>
      <pathelement location="${wsp.home}/lib/xalan.jar"/>
      <pathelement location="${wsp.home}/lib/xercesImpl.jar"/>
      <pathelement location="${wsp.home}/lib/j2ee.jar"/>
      <pathelement location="${wsp.home}/lib"/>
      <pathelement path="build/classes"/>
    </classpath>
    </javac>
</target>

<target name="run" depends="build">
    <echo>java.home=${java.home}</echo>
  <java classname="com.samples.SecuringWS" fork="true">
    <classpath>
      <pathelement location="${wsp.home}/lib/openssowssproviders.jar"/>
      <pathelement location="${wsp.home}/lib/ldapjdk.jar"/>
      <pathelement location="${wsp.home}/lib/webservices-rt.jar"/>
      <pathelement location="${wsp.home}/lib/openssoclientsdk.jar"/>
      <pathelement location="${wsp.home}/lib/xalan.jar"/>
      <pathelement location="${wsp.home}/lib/xercesImpl.jar"/>
      <pathelement location="${wsp.home}/lib/j2ee.jar"/>
      <pathelement location="${wsp.home}/lib"/>
      <pathelement path="build/classes"/>
    </classpath>
    </java>
  </target>

  <target name="clean">
    <delete dir="dist"/>
    <delete dir="build"/>
  </target>
</project>

Modify /opt/wsp/lib/AMConfig.properties depending on your setup, so that the StandAloneStockClient sample sends a secure web service request:

com.iplanet.services.debug.level=error
com.iplanet.services.debug.directory=/tmp/wss
com.iplanet.am.naming.url=http://opensso-host:port/opensso/namingservice
com.sun.identity.agents.app.username=amadmin
com.iplanet.am.service.password=amadmin-password
com.iplanet.am.service.secret=
am.encryption.pwd=
com.sun.identity.client.encryptionKey=
com.iplanet.am.server.protocol=http
com.iplanet.am.server.host=opensso-host
com.iplanet.am.server.port=port
com.iplanet.am.services.deploymentDescriptor=/opensso
com.iplanet.am.cookie.name=iPlanetDirectoryPro
com.sun.identity.saml.xmlsig.keystore=/opt/wsp/resources/keystore.jks
com.sun.identity.saml.xmlsig.storepass=/opt/wsp/resources/.storepass
com.sun.identity.saml.xmlsig.keypass=/opt/wsp/resources/.keypass
com.sun.identity.saml.xmlsig.certalias=cert-alias
com.sun.identity.loginurl=http://your-opensso-hostname:port/opensso/UI/Login
com.sun.identity.liberty.authnsvc.url=http://opensso-host:port/opensso/Liberty/authnsvc

Execute the StandAloneStockClient. For example:
```
/share/builds/components/ant/1.6.5/bin/ant -f build.xml.
```
You should see the requests and responses. Also, check the Tomcat 6.0 agent debug file.