Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Apache Tomcat 6.0

Pre-Installation Tasks for the Tomcat 6.0 Version 3.0 Agent

Setting Your JAVA_HOME Environment Variable

Version 3.0 policy agents, including the agentadmin program, require JDK 1.5 or later on the server where you plan to install the agent. Before you install the Tomcat 6.0 version 3.0 agent, set your JAVA_HOME environment variable to point to the JDK installation directory.

Downloading and Unzipping the Distribution File

ProcedureTo Download and Unzip the Distribution File

  1. Login to the server where you want to install the agent.

  2. Create a directory to unzip the distribution file.

    This guide uses Agent-HomeDirectory to represent the directory where you unzip the distribution file.

  3. Download the distribution file from one of the following sites:

    The following table shows the files and directories after you unzip the agent distribution file, which are in the following directory:


    Agent-HomeDirectory is where you unzipped the agent distribution file.

    File or Directory 


    README.txt and license.txt

    Readme and license files 


    agentadmin and agentadmin.bat programs


    Template, properties, and XML files 


    license.log file. Do not edit this file.


    Agent application (agentapp.war) and related file. For information, see Deploying the Agent Application.


    Log files written by the agentadmin or agentadmin.bat program:

    • /audit contains local audit trail for the agent instance.

    • /debug contains the debug files for the agent instance when the agent runs in debug mode.


    Required JAR files 


    Required properties files 


    Policy agent sample application. For information, see Deploying the Java EE Policy Agent Sample Application.

Creating a Password File

A password file is an ASCII text file with only one line specifying the password in clear text. By using a password file, you are not forced to expose a password at the command line during the agent installation. When you install the Tomcat 6.0 version 3.0 agent using the agentadmin program, you are prompted to specify paths to following password files:

ProcedureTo Create a Password File

  1. Create an ASCII text file for the agent profile. For example: /tmp/tomcat6agentpw

  2. If you want the agentadmin program to automatically create the agent profile in OpenSSO Enterprise server during the installation, create another password file for the agent administrator. For example: /tmp/agentadminpw

  3. Using a text editor, enter the appropriate password in clear text on the first line in each file.

  4. Secure each password file appropriately, depending on the requirements for your deployment.

Installing the Tomcat 6.0 Scripts on Windows Systems

The Tomcat 6.0 installation file for Windows (.exe extension) does not install certain scripts and related files required by the Tomcat 6.0 version 3.0 agent. Therefore, after you install the Tomcat 6.0 web container on a Windows system, you must copy the scripts from a Tomcat 6.0 .zip distribution file.

ProcedureTo Install the Tomcat 6.0 Scripts on Windows

  1. In a directory separate from the Tomcat 6.0 .exe installation, download the Tomcat 6.0 .zip distribution file from

    For example, download

  2. Make sure that the CATALINA_HOME environment variable is set to your Tomcat 6.0 .exe installation.

  3. Unzip the Tomcat 6.0 .zip distribution file.

  4. Copy the following files from the unzipped bin directory to the Tomcat 6.0 bin directory (${CATALINA_HOME}\bin):

    • All .bat scripts

    • catalina-tasks.xml

    • .jar files

Creating an Agent Administrator

An agent administrator can manage agents in OpenSSO Enterprise, including:

ProcedureTo Create an Agent Administrator

  1. Login to OpenSSO Enterprise Administration Console.

  2. Create a new agents administrator group:

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

    2. Click New.

    3. In ID, enter the name of the group. For example: agentadmingroup

    4. Click OK.

  3. Create a new agent administrator user and add the agent administrator user to the agents administrator group:

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

    2. Click New and provide the following values:

      • ID: Name of the agent administrator. For example: agentadminuser

        This is the name you will use to login to the OpenSSO Enterprise Console .

      • First Name (optional), Last Name, and Full Name.

        For simplicity, use the same name for each of these values that you specified for ID.

      • Password (and confirmation)

      • User Status: Active

    3. Click OK.

    4. Click the new agent administrator name.

    5. On the Edit User page, click Group.

    6. Add the agents administrator group from Available to Selected.

    7. Click Save.

  4. Assign read and write access to the agents administrator group:

    1. Click Access Control, realm-name, Privileges and then on the new agents administrator group link.

    2. Check “Read and write access to all configured Agents”.

    3. Click Save.

Next Steps

Login into the OpenSSO Enterprise Console as the new agent administrator. The only available top-level tab is Access Control. Under realm-name, you will see only the Agents tab and sub tabs.