test

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Apache Tomcat 6.0

Optional Post-Installation Tasks for the Tomcat 6.0 Version 3.0 Agent

Changing the Password for an Agent Profile

After you install the agent, you can change the agent profile password, if required for your deployment.

ProcedureTo Change the Password for an Agent Profile

  1. On the OpenSSO Enterprise server:

    1. Login into the OpenSSO Administration Console.

    2. Click Access Control, realm-name, Agents, J2EE, and then the name of the agent profile you want to update.

      The Console displays the Edit page for the agent profile.

    3. Enter and confirm the new unencrypted password.

    4. Click Save.

  2. On the server where the Tomcat 6.0 version 3.0 agent is installed:

    1. In the agent profile password file, replace the old password with the new unencrypted password.

    2. Change to the PolicyAgent-base/bin directory.

    3. Encrypt the new password using the agentadmin --encrypt command following this syntax.

      agentadmin --encrypt agent-instance password-file

      For example:

      # ./agentadmin --encrypt Agent_001 tomcat6agentpw

      The agentadmin --encrypt command returns the new encrypted password. For example:

      ASEWEJIowNBJHTv1UGD324kmT==

    4. In the agent-instance/config/OpenSSOAgentBootstrap.properties file, set the following property to the new encrypted password from the previous step. For example:

      com.iplanet.am.service.secret=ASEWEJIowNBJHTv1UGD324kmT==

    5. Restart the Tomcat 6.0 instance that is being protected by the policy agent.

Creating the Necessary URL Policies

If the Tomcat 6.0 version 3.0 agent is configured to operate in the URL_POLICY or ALL filter mode, you must create the appropriate URL policies. For instance, if the agent is available on port 8080 using the HTTP protocol, you must create at minimum, a policy to allow access to the following resource:


http://myhost.mydomain.com:8080/agentsample

where agentsample is the context URI for the sample application.

If no policies are defined and the agent is configured to operate in the URL_POLICY or ALL filter mode, then no user is allowed access to the resources protected by the Tomcat 6.0 version 3.0 agent.

For more information, see:

Configuring J2EE Declarative Security for Tomcat 6.0 Web Applications

This section describes how to configure J2EE declarative security for the Tomcat 6.0 Manager, Administration, and Host Manager web applications, including:

Setting the Agent Filter Modes

By default, the Tomcat 6.0 version 3.0 agent protects the Tomcat Manager, Administration, and Host Manager web applications with J2EE security. This default configuration is set by the agent installer, which sets the Agent Filter Mode (com.sun.identity.agents.config.filter.mode property) to J2EE_POLICY in the Tomcat 6.0 version 3.0 agent configuration.

If you prefer, you can protect the Manager, Administration, and Host Manager web applications with a filter mode other than J2EE_POLICY, depending on the requirements for your deployment. For example, you can change the filter mode for these applications to URL_POLICY or ALL.

ProcedureTo Set the Agent Filter Modes

  1. Log in to the OpenSSO Enterprise Administration Console.

  2. Click Access Control, realm-name, Agents, J2EE, and then the name of the Tomcat 6.0 version 3.0 agent.

  3. Click General and add the Agent Filter Mode as required by your deployment for:

    • Manager web application (manager)

    • Administration web application (admin)

    • Host Manager web application (host-manager)

    The corresponding properties are:

    com.sun.identity.agents.config.filter.mode[manager]
com.sun.identity.agents.config.filter.mode[admin]
com.sun.identity.agents.config.filter.mode[host-manager]

  4. Click Save.

  5. The com.sun.identity.agents.config.filter.mode property is not hot-swappable, so you must restart the OpenSSO Enterprise web container for the new values to take effect.

Creating OpenSSO Enterprise Users and Groups

In this task, you create new OpenSSO Enterprise users and groups who will be able to access the Tomcat 6.0 version 3.0 Manager, Administration, and Host Manager web applications.

Note –

In Access Manager 7.1 and Access Manager 7 2005Q4, users were assigned specific roles. OpenSSO Enterprise uses groups rather than roles for the same functionality.

ProcedureTo Create OpenSSO Enterprise Users and Groups

  1. Log in to the OpenSSO Enterprise Administration Console.

  2. Click Access Control, realm-name, Subjects, and then User.

  3. Create the following new users, as required by your deployment:

    • Manager user: A user who will be assigned to the manager group and will be able to log into the Manager web application.

    • Administrator user: A user who will be assigned to the admin group and will be able to log into the Administration and Host Manager web applications.

  4. Click Access Control, realm-name, Subjects, and then Group.

  5. Create the following new groups:

    • Manager group named manager

    • Administrator group named admin

  6. Assign the new users created in Step 3 to their respective groups:

    • Assign the Manager user to the Manager group (manager).

    • Assign the Administrator user to the Administrator group (admin).

  7. Save all changes to the new users and groups.

Allowing an OpenSSO Enterprise User to Access the Manager Web Application

In this task, you edit the Tomcat 6.0 version 3.0 Manager web.xml file to allow an OpenSSO Enterprise user to access the Manager web application.

ProcedureTo Allow an OpenSSO Enterprise User to Access the Manager Web Application

  1. Change to the following directory for the Tomcat 6.0 version 3.0 instance:

    $CATALINA_HOME/server/webapps/manager/WEB-INF

  2. In the web.xml file, find the user and role information for the Manager role.

    This role is defined in the <role-name> element under the <security-role> element.

  3. Delete the Manager security role.

  4. Create a new Manager security role using the user and group that you created in the OpenSSO Enterprise Console, as described in Creating OpenSSO Enterprise Users and Groups.

    For example:

    <security-role>
id=manager,ou=group,dc=realm-name,dc=example,dc=com
</security-role>

  5. Replace the Manager role defined in the <role-name> element under the <auth-constraint> element with the contents of the <role-name> element as described in the previous step.

    For example:

    <auth-constraint>
<role-name>id=manager,ou=group,dc=realm-name,dc=example,dc=com</role-name>
</auth-constraint>

  6. Save the web.xml file.

Allowing an OpenSSO Enterprise User to Access the Administration Web Application

In this task, you edit the Administration web application's web.xml file to allow an OpenSSO Enterprise user to access the Administration web application.

ProcedureTo Allow an OpenSSO Enterprise User to Access the Administration Web Application

  1. Change to the following directory for the Tomcat 6.0 version 3.0 instance:

    $CATALINA_HOME/server/webapps/admin/WEB-INF

  2. In the web.xml file, find the user and role information for the Administrator role.

    This role is defined in the <role-name> element under the <security-role> element.

  3. Delete the Administrator security role.

  4. Create a new Administrator security role using the user and group that you created in the OpenSSO Enterprise Console, as described in Creating OpenSSO Enterprise Users and Groups.

    For example:

    <security-role>
<role-name>id=admin,ou=group,dc=realm-name,dc=example,dc=com</role-name>
</security-role>

  5. Replace the Administrator role defined in the <role-name> element under the <auth-constraint> element with the contents of the <role-name> element as described in the previous step.

    For example:

    <auth-constraint>
<role-name>id=admin,ou=group,dc=realm-name,dc=example,dc=com</role-name>
</auth-constraint>

  6. Save the web.xml file.

  7. Restart the Tomcat 6.0 web container.

Allowing an OpenSSO Enterprise User to Access the Host Manager Web Application

In this task, you edit the Host Manager web application's web.xml file to allow an OpenSSO Enterprise user to access the Host Manager web application.

The steps to configuring the Host Manager web application with declarative security are similar to the steps for the Administration web application. Both applications are accessible by users assigned to the admin group.

ProcedureTo Allow an OpenSSO Enterprise User to Access the Host Manager Web Application

  1. Change to the following directory for the Tomcat 6.0 version 3.0 instance:

    $CATALINA_HOME/server/webapps/host-manager/WEB-INF

  2. In the web.xml file, find the user and role information for the Host Manager web application role.

    This role is defined in the <role-name> element under the <security-role> element.

  3. Delete the Host Manager web application security role.

  4. Create a new Host Manager web application security role using the user and group that you created in the OpenSSO Enterprise Console, as described in Creating OpenSSO Enterprise Users and Groups.

    For example:

    <security-role>
<role-name>id=host-manager,ou=group,dc=realm-name,dc=example,dc=com</role-name>
</security-role>

  5. Replace the Host Manager web application role defined in the <role-name> element under the <auth-constraint> element with the contents of the <role-name> element as described in the previous step.

    For example:

    <auth-constraint>
<role-name>id=host-manager,ou=group,dc=realm-name,dc=example,dc=com</role-name>
</auth-constraint>

  6. Save the web.xml file.

  7. Restart the Tomcat 6.0 web container.

Deploying the Java EE Policy Agent Sample Application

Deploying the policy agent sample application is optional. However. after you install the Tomcat 6.0 version 3.0 agent, consider deploying the sample application to help you better understand the key features, functions, and configuration options of Java EE agents, including:

The sample application can be especially useful if you are writing a custom agent application.

After you install the Tomcat 6.0 version 3.0 agent, the sample application is available as:

PolicyAgent-base/sampleapp/dist/agentsample.war

For information about compiling, deploying, and running the sample application, see the readme.txt file in the /sampleapp directory.

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.

ProcedureTo 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.

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

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

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

  4. 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

  5. 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"/>

  6. 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

  7. 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.

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

  9. 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.

  10. 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/

  11. 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.

ProcedureTo Configure the StockService Sample

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

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

  3. Unzip openssowssproviders.zip in /opt/wsp/.

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

    cd /opt/wsp/samples
mkdir tomcat

  5. Copy the GlassFish sample files to the new tomcat directory:

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

  6. Rename glassfish.properties for Tomcat 6.0:

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

  7. 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

  8. 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>

  9. 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

  10. 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

  11. 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>

  12. 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>

  13. 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

ProcedureTo Configure the StandAloneStockClient Sample

  1. Change to the StandAloneStockClient directory:

    cd /opt/wsp/samples/tomcat/StandAloneStockClient

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

  3. 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>

  4. 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

  5. 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.