Chapter 4 Post-Installation Tasks of Policy Agent 2.2 for Apache Tomcat Servlet/JSP Container

This chapter provides information about configuration and other post-installation considerations and tasks as follows:

• Common Post-Installation Steps for All J2EE Agents in Policy Agent 2.2

• Post-Installation Steps Specific to Agent for Apache Tomcat Servlet/JSP Container

• Conditional Post-Installation Steps for J2EE Agents in Policy Agent 2.2

After completing the applicable tasks described in this chapter, perform the tasks to configure the agent to your site's specific needs as explained in Chapter 5, Managing Policy Agent 2.2 for Apache Tomcat Servlet/JSP Container.

Common Post-Installation Steps for All J2EE Agents in Policy Agent 2.2

The tasks described in this section apply to all J2EE agent installations.

Updating the Agent Profile for J2EE Agents in Policy Agent 2.2

This procedure is not required. The agent profile is created and updated in Access Manager Console. The agent profile should originally be created prior to installing an agent. However, after you install a J2EE agent, you can update the agent profile at anytime. If you do update the agent profile in Access Manager Console, you must then configure the J2EE agent accordingly as described in this section.

To Update the Agent Profile for J2EE Agents in Policy Agent 2.2

Before You Begin

Change the agent profile in Access Manager using Access Manager Console. For more information about the agent profile, see Creating a J2EE Agent Profile.

1. Change the password in the password file to match the new password you just created in Access Manager Console as a part of the agent profile.

   The password file should originally have been created as a J2EE agent pre-installation task. For more information about pre-installation, seePreparing to Install Agent for Apache Tomcat Servlet/JSP Container.

2. In the command line, issue the agentadmin --encrypt command to encrypt the new password.

   For more information on this command, see agentadmin --encrypt.

3. Access the J2EE agent AMAgent.properties configuration file at the following location:

   PolicyAgent-base/AgentInstance-Dir/config

4. In this configuration file, edit the property for the agent ID to match the new ID in the agent profile as follows:

   com.sun.identity.agents.app.username = agentID
   

   where agentID represents the new agent ID that you created for the agent profile in Access Manager Console.

5. Edit the property for the agent password as follows:

   com.iplanet.am.service.secret = encryptedPassword
   

   where encryptedPassword represents the new encrypted password you created when you issued the agentadmin --encrypt command.

6. Restart the J2EE agent container.

   The container needs to be restarted because neither property that you edited in this task is hot-swap enabled.

Deploying the Agent Application for J2EE Agents in Policy Agent 2.2

The task described in this section is required. Deploy the URI for the agent application using the deployment container. The agent application is a housekeeping application used by the agent for notifications and other internal functionality. This application is bundled with the agent binaries and can be found at the following location:

PolicyAgent-base/etc/agentapp.extension

where extension refers to the .war extension or the .ear extension. The extension varies depending on the deployment container.

For more information about the Policy Agent base directory (PolicyAgent-base), see J2EE Agent Directory Structure in Policy Agent 2.2.

The agentapp application has to be deployed as a post installation step. In order for the agent to function correctly, this application must be deployed on the agent-protected deployment container instance using the same URI that was supplied during the agent installation process (optionally, you can add a hyper link to and from the relevant prompt). For example during the installation process, if you entered /agentapp as the deployment URI for the agent application, then use that same context path to deploy the .war or .ear file in the deployment container.

Using the administration console or command-line utilities of your deployment container, deploy this application using Application Context Path as the URI specified during agent installation.

Post-Installation Steps Specific to Agent for Apache Tomcat Servlet/JSP Container

Once you have installed Policy Agent 2.2 for Apache Tomcat Servlet/JSP Container and you have performed the post-installation steps that apply to all J2EE agents in the Policy Agent 2.2 release, complete the following agent-specific steps.

Installing the Agent Filter for the Deployed Application on Agent for Apache Tomcat Servlet/JSP Container

The agent filter can be installed by modifying the deployment descriptor of the application that needs to be protected.

To Install the Agent Filter for the Deployed Application on Agent for Apache Tomcat Servlet/JSP Container

By default, only the Manager web application and the administration web application are protected when the agent filter is in the J2EE_POLICY mode.

The following steps explain how to install the agent filter for the application you want the agent to protect:

1. To install the agent filter, ensure that the application is not currently deployed on Apache Tomcat Servlet/JSP Container.

   If it is currently deployed, remove it before proceeding any further.

2. Create the necessary backup files for the deployed application's deployment descriptors.

   Since you will modify the deployment descriptor in the next step, creating backup files at this point is important.

3. (Conditional) If the agent filter is not deployed in the global deployment descriptor, modify the deployed application's deployment descriptor by editing the application's web.xml descriptor.

   1. Add the <filter> element by adding the following lines:

      <filter> <filter-name>Agent</filter-name> <display-name>Agent</display-name> <description>Identity Server Policy Agent Filter</description> <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class> </filter>

   2. Add the <filter-mapping> element by adding the following lines:

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

Next Steps

If you want to protect your application with J2EE declarative security, you must first perform the tasks described in Configuring J2EE Declarative Security for Apache Tomcat Servlet/JSP Container—Related Web Applications. You can also access the sample application in the PolicyAgentBase/sampleapp directory to learn how to build and deploy an application. The sampleapp directory is by no means a full fledged J2EE application. Rather it is a simple application that provides you with a quick reference to application specific deployment descriptors and various deployment modes of a J2EE agent. Once you successfully deploy the sampleapp and test all of its features, you can use it as a reference to other applications that will be protected by the J2EE agent.

Once the web.xml deployment descriptor is modified to reflect the new <DOCTYPE> and <filter> elements, the agent filter is added to the application. You can now redeploy your application on Apache Tomcat Servlet/JSP Container.

Ensure that role-to-principal mappings in container specific deployment descriptors are replaced with Access Manager roles or principals. You can retrieve Access Manager roles or principals for Access Manager 7 by issuing the agentadmin --getUuid command. For more information on the agentadmin --getUuid command, see agentadmin --getUuid.

You can also retrieve the universal ID for the user (UUID) using Access Manager 7 Console to browse the user profile.

Conditional Post-Installation Steps for J2EE Agents in Policy Agent 2.2

Steps described in this section might be required, depending on your site's specific deployment.

Configuring J2EE Declarative Security for Apache Tomcat Servlet/JSP Container—Related Web Applications

The role-to-principal mappings in Apache Tomcat Servlet/JSP Container deployment descriptors must be replaced with Access Manager roles or principals. The tasks described in this section include steps for changing the deployment descriptors of the Manager web application, the administration web application, and the host manager web application, thereby configuring J2EE declarative security for these applications.

• To Create and Assign Access Manager Roles

• To Allow Access Manager Users to Access the Manager Web Application

• To Allow Access Manager Users to Access the Administration Web Application

• To Allow Access Manager Users to Access the Host Manager Web Application

By default, Agent for Apache Tomcat Servlet/JSP Container protects the Manager web application, the administration web application, and the host manager web application with J2EE security. This default configuration is established by the J2EE agent installer, which sets the agent filter mode to J2EE_POLICY in the J2EE agent AMAgent.properties configuration file as follows:

com.sun.identity.agents.config.Filter.mode = J2EE_POLICY

To protect the Manager web application, the administration web application, and the host manager web application with a filter mode other than J2EE_POLICY, change or add to the preceding setting accordingly in order to change the filter mode for these applications to URL_POLICY mode or ALL mode. The following example demonstrates these three applications set to specific filter modes. The administration web application is set to URL_POLICY mode while the Manager web application and the host manager web application are set to ALL mode.

com.sun.identity.agents.config.Filter.mode[admin] = URL_POLICY
com.sun.identity.agents.config.Filter.mode[manager] = ALL
com.sun.identity.agents.config.Filter.mode[host-manager] = ALL

After you have set the filter mode for each of these applications to the mode that best suits your site's deployment, perform the steps detailed in the following task descriptions.

To Create and Assign Access Manager Roles

Using Access Manager Console, create Administrator users and Manager users as outlined in this task. For detailed information about Access Manager users and roles, see Sun Java System Access Manager 7 2005Q4 Administration Guide.

1. Create the following roles: an administer role named admin and a manager role named manager.

   The tasks that follow explain how to edit the appropriate web.xml files in Apache Tomcat Servlet/JSP Container to add these role names. If the role names in Access Manager do not match role names in the respective web.xml files, the result is that access is denied to the respective Apache Tomcat Servlet/JSP Container application.

2. Create and assign users to the newly created roles.

   Users assigned to the admin role can log in to the administration web application and the host manager web application. Users assigned the manager role can log in to the Manager web application.

To Allow Access Manager Users to Access the Manager Web Application

Using the Apache Tomcat Servlet/JSP Container instance, add the appropriate users and roles to the Manager web application's web.xml file as described in this task. The method for adding users to the web.xml file is not the same for Access Manager 7 and Access Manager 6.3. The differences relate to how user and role information is retrieved. Access Manager 7 takes advantage of a universal ID (UUID) system of identification while Access Manager 6.3 uses the distinguished name (DN) of users. Universal ID retrieval is achieved with the agentadmin program. For more information about the specific agentadmin commands to use, see agentadmin --getUuid.

1. Change to the following directory:

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

2. Open the web.xml file.

3. Retrieve user and role information for the Manager role using the appropriate method according to the version of Access Manager you are configuring as follows:

   Access Manager 7

   Use Universal ID for identification information.

   Access Manager 6.3 Patch 1 or Greater

   Use DN for identification information.

4. Delete the Manager security role.

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

5. Create a new Manager security role using the user and role information created previously in Access Manager as described in To Create and Assign Access Manager Roles.

   The following examples demonstrate how to create a new Manager security role for Access Manager 7 and Access Manager 6.3 Patch 1 or greater.

   • Security Role Element for Access Manager 7

     For this example, the following values apply to the universal ID for the Manager role in Access Manager 7, where realmName is a representation of organization name:

     userName

     id=manager

     IdType

     ou=role

     realmName

     dc=subexample,dc=example,dc=com

     The preceding values are used in the following example of a universal ID for the Manager role in Access Manager 7:

     id=manager,ou=role,dc=subexample,dc=example,dc=com

     The following is an example of a security role element, given the preceding universal ID information for the Manager role in Access Manager 7:

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

   • Security Role Element for Access Manager 6.3 Patch 1 or Greater

     The following is an example of a role DN for the Manager role in Access Manager 6.3 where the organization is represented by dc=subexample,dc=example,dc=com:

     cn=manager,ou=groups,dc=subexample,dc=example,dc=com

     The following is an example of a security role element, given the preceding DN information for the Manager role in Access Manager 6.3:

     <security-role>
     <role-name>cn=manager,ou=groups,dc=subexample,dc=
     example,dc=com</role-name></security-role>

6. Replace the Manager role defined in the <role-name> element under the <auth-constraint> element.

   This Manager role should be replaced with the contents of the <role-name> element as described in the previous step and demonstrated as follows:

   • Manager Role for Access Manager 7

     After the Manager role definition has been replaced, the <auth-constraint> element for the Manager role in Access Manager 7 for the dc=subexample,dc=example,dc=com realm would appear as such:

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

   • Manager Role for Access Manager 6.3 Patch 1 or Greater

     After the Manager role definition has been replaced, the <auth-constraint> element for the Manager role in Access Manager 6.3 for the dc=subexample,dc=example,dc=com organization would appear as such:

     <auth-constraint>
     <role-name>cn=manager,ou=groups,dc=subexample,dc=example,dc=com</role-name>
     </auth-constraint>

To Allow Access Manager Users to Access the Administration Web Application

In the Apache Tomcat Servlet/JSP Container instance, add the appropriate users and roles to the administration web application's web.xml file as described in this task. This task is similar to the preceding task in that the two tasks both apply to Access Manager 6.3 Patch 1 or greater and Access Manager 7. Use the information in this task that applies to your site's deployment.

1. Change to the following directory:

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

2. Open the web.xml file.

3. Retrieve user and role information for the Administrator role using the appropriate method according to the version of Access Manager you are configuring:

   Access Manager 7

   Use Universal ID for identification information.

   Access Manager 6.3 Patch 1 or Greater

   Use DN for identification information.

4. Delete the Administrator security role.

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

5. Create a new Administrator security role using the user and role information created previously in Access Manager as described in To Create and Assign Access Manager Roles.

   The following examples demonstrate how to create a new Administrator security role for Access Manager 7 and Access Manager 6.3 Patch 1 or greater.

   • Security Role Element for Access Manager 7

     For this example, the following values apply to the universal ID for the Administrator role in Access Manager 7, where realmName is a representation of organization name:

     userName

     id=admin

     IdType

     ou=role

     realmName

     dc=subexample,dc=example,dc=com

     The preceding values are used in the following example of a universal ID for the Administrator role in Access Manager 7:

     id=admin,ou=role,dc=subexample,dc=example,dc=com

     The following is an example of a security role element, given the preceding universal ID information for the Administrator role in Access Manager 7:

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

   • Security Role Element for Access Manager 6.3 Patch 1 or Greater

     The following is an example of a role DN for the Administrator role in Access Manager 6.3 where the organization is represented by dc=subexample,dc=example,dc=com:

     cn=admin,ou=groups,dc=subexample,dc=example,dc=com

     The following is an example of a security role element given the preceding DN information for the Administrator role in Access Manager 6.3:

     <security-role>
     <role-name>cn=admin,ou=groups,dc=subexample,dc=
     example,dc=com</role-name></security-role>

6. Replace the Administrator role defined in the <role-name> element under the <auth-constraint> element.

   This Administrator role should be replaced with the contents of the <role-name> element as described in the previous step and demonstrated as follows:

   • Administrator Role for Access Manager 7

     After the Administrator role definition has been replaced, the <auth-constraint> element for the Administrator role in Access Manager 7 for the dc=subexample,dc=example,dc=com realm would appear as such:

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

   • Administrator Role for Access Manager 6.3 Patch 1 or Greater

     After the Administrator role definition has been replaced, the <auth-constraint> element for the Administrator role in Access Manager 6.3 for the dc=subexample,dc=example,dc=com organization would appear as such:

     <auth-constraint>
     <role-name>cn=admin,ou=groups,dc=subexample,dc=example,dc=com</role-name>
     </auth-constraint>

To Allow Access Manager Users to Access the Host Manager Web Application

Follow similar steps to those described in To Allow Access Manager Users to Access the Administration Web Application by editing the web.xml file of the host manager web application at the following location:

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

All the remaining steps for configuring the host manager web application with declarative security are the same as for the administration web application.

Since both applications are accessible by users assigned to the role admin, the web.xml files for both applications must be edited in the same manner.

Creating the Necessary URL Policies

If the agent is installed and configured to operate in the URL_POLICY mode or ALL mode, the appropriate URL policies must be created. For instance, if Apache Tomcat Servlet/JSP Container is available on port 8080 using HTTP protocol, at least a policy must be created to allow access to the following resource:

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

where sampleApp is the context URI for the sample application.

If no policies are defined and the agent is configured to operate in the URL_POLICY mode or ALL mode, then no user is allowed access to Apache Tomcat Servlet/JSP Container resources. See Sun Java System Access Manager 7 2005Q4 Administration Guide to learn how to create these policies using the Access Manager Console or command-line utilities.