test

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Apache Tomcat 6.0

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

Creating an Agent Profile

If you created the agent profile using the agentadmin program, continue with Adding Absolute URIs to the Tomcat 6.0 Version 3.0 Agent Profile.

The Tomcat 6.0 version 3.0 agent uses an agent profile to communicate with OpenSSO Enterprise server. You can create an agent profile using any of these three methods:

ProcedureTo Create an Agent Profile in the OpenSSO Enterprise Console

  1. Login into the OpenSSO Enterprise Administration Console as amAdmin.

  2. Click Access Control, realm-name, Agents, and then J2EE.

  3. Under Agent, click New.

  4. In the Name field, enter the name for the new agent profile. For example: Tomcat6AgentProfile

  5. Enter and confirm the Password.

    Important: This password must be the same password that you enter in the agent profile password file that you specify when you run the agentadmin program to install the agent.

  6. In the Server URL field, enter the OpenSSO Enterprise server URL.

    For example: http://openssohost.example.com:8080/opensso

  7. In the Agent URL field, enter the URL for the agent application ().

    For example: http://agenthost.example.com:8090/agentapp

    The agentapp is a housekeeping application used by the agent for notifications and other functions such as cross domain single sign-on (CDSSO) support. For more information, see Deploying the Agent Application.

  8. Click Create.

    The console creates the agent profile and displays the J2EE Agent page again with a link to the new agent profile, Tomcat6AgentProfile.

  9. Click the link to the new agent profile.

  10. For Login Form URI, add the following entries:

    /manager/AMLogin.html
/host-manager/AMLogin.html

    This step allows the agent to protect the manger and host-manager by default.

  11. Click Save.

    This change (com.sun.identity.agents.config.login.form property) is hot-swappable, so you do not need to restart the OpenSSO Enterprise web container for these values to take effect.

    Tip –

    Make a note of the values you specified for the agent profile, including the profile name, password, server URL, and agent URL. You will need these values when you install the Tomcat 6.0 version 3.0 agent using the agentadmin program.

Adding Absolute URIs to the Tomcat 6.0 Version 3.0 Agent Profile

Note –

If you performed this task when you created the agent profile, you can skip it here.

ProcedureTo Add Absolute URIs to the Tomcat 6.0 Version 3.0 Agent Profile

  1. Log in to the OpenSSO Enterprise Administration Console.

  2. Click Access Control, Top Level Realm, Agents, J2EE, and then the agent profile for theTomcat 6.0 version 3.0 agent.

  3. On the Edit page, click Application and then Login Processing.

  4. For Login Form URI, add the following entries:

    /manager/AMLogin.html
/host-manager/AMLogin.html

  5. Click Save.

    This change (com.sun.identity.agents.config.login.form property) is hot-swappable, so you do not need to restart the OpenSSO Enterprise web container for these values to take effect.

Creating the manager and admin Groups

ProcedureTo Create the host-manager and admin Groups

  1. Login to OpenSSO Enterprise Administration Console.

  2. Create two new groups: manager and admin, as follows:

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

    2. Click New.

    3. In ID, enter the name of the group. For example: manager or admin

    4. Click OK.

      Repeat these steps for the other group.

  3. To test access to the manager and host-manager applications, add several test users to each group.

  4. Create a policy with two rules and allow access to the manager and admin groups. For example:

    http://sso-host.example.com:8080/host-manager/*

    http://sso-host.example.com:8080/manager/*

  5. If the redirect loop issue is a concern, set the Cookie Encode property to Yes in the OpenSSO Enterprise server:

    1. In the console, click Configuration, Server and Sites, and the OpenSSO Enterprise Server Instance name.

    2. Click Security and then Cookie. By default Encode Cookie is set to No.

    3. Click Inheritance Settings, deselect Encode Cookie, and then click Save.

      You can now change the cookie encoding option.

    4. Click Back to Server Profile.

    5. Set Cookie Encoding to Yes and click Save.

  6. Make the following Tomcat 6.0 manager and host-manager application changes:

    1. For the manager application, in the $CATALINA_HOME/webapps/manager/WEB-INF/web.xml, change <role-name>manager</role-name> to:

      <role-name>id=manager,ou=group,dc=opensso,dc=java,dc=net</role-name>

    2. For the host-manager application, in the $CATALINA_HOME/webapps/host-manager/WEB-INF/web.xml, change <role-name>admin</role-name> to:

      <role-name>id=admin,ou=group,dc=opensso,dc=java,dc=net</role-name>

      Note. The dc=opensso,dc=java,dc=net part in the manager and admin role values is used because OpenSSO Enterprise is deployed using the default mode. If you have a custom setup and the DN is different, change the value for your deployment.

  7. Restart the OpenSSO Enterprise server.

Deploying the Agent Application

The agent application (agentapp.war) is a housekeeping application used by the agent for notifications and other functions such as cross domain single sign-on (CDSSO) support.

ProcedureTo Deploy the Agent Application

  1. The agent application (agentapp.war) is bundled with the tomcat_v6_agent_3.zip distribution file and is available as follows after you unzip the file:

    PolicyAgent-base/etc/agentapp.war

  2. Deploy agentapp.war on the Tomcat 6.0 instance by copying agentapp.war to the Tomcat 6.0 webapps directory.

    Important: You must use the same deployment URI that you specified for the “Agent URL” prompt during the agent installation. For example, if you accepted the default value (/agentapp) as the deployment URI for the agent application, use this same URI to deploy agentapp.war.

Configuring Tomcat Applications Protected by the Tomcat 6.0 Version 3.0 Agent

Installing the Agent Filter for a Deployed Application Protected by the Tomcat 6.0 Version 3.0 Agent

This task is required depending on how you answered the Install policy agent in global web.xml file prompt during the Tomcat 6.0 Version 3.0 agent installation:

ProcedureTo Install the Agent Filter for a Deployed Application Protected by the Tomcat 6.0 Version 3.0 Agent

  1. Ensure that the application you want to protect is not currently deployed on Tomcat 6.0.

    If the application is deployed, undeploy it before continuing.

  2. Backup the application's web.xml file before you modify the descriptors.

    The backup copy can be useful if you need to uninstall the agent.

  3. Edit the application's descriptors in the web.xml file:

    1. Set the <DOCTYPE> element as shown in the following example:


      <!DOCTYPE web-app version="2.4"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

      Note: Tomcat 6.0 supports the Java Servlet specification version 2.4. Version 2.4 is fully backward compatible with version 2.3. Therefore, all existing servlets should work without modification or recompilation.

    2. Add the <filter> elements to the deployment descriptor.

      Specify the agent filter as the first <filter> element and the agent filter mapping as the first <filter-mapping> element. For example:


      <web-app>
...
    <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>
...
</web-app>

  4. Restart the Tomcat 6.0 web container.

  5. Deploy (or redeploy) the application on the Tomcat 6.0 web container.

    The agent filter is then added to the application.

    Note: You can also protect an application with Java EE declarative security. To learn more about protecting your application with Java EE declarative security, consider Deploying the Java EE Policy Agent Sample Application.