test

Sun Java System Access Manager Policy Agent 2.2 Guide for Apache Tomcat 5.5 Servlet/JSP Container

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.

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.

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

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

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

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