test

Sun Java System Access Manager Policy Agent 2.2 Guide for IBM WebSphere Application Server 6.0

Post-Installation Steps Specific to Agent for IBM WebSphere Application Server 6.0

Once you have installed Policy Agent 2.2 for IBM WebSphere Application Server 6.0 and you have performed the post-installation steps that apply to all J2EE agents in the Policy Agent 2.2 release, complete the agent-specific procedures detailed in this section. For more information about concepts discussed in this section regarding IBM WebSphere Application Server 6.0, see High-Level Architecture of Agent for IBM WebSphere Application Server 6.0.

This section consists of the following subsections:

The configuration described in this section is related to applications deployed on the instance of IBM WebSphere Application Server 6.0 that the agent will protect. The first subsection describes the configuration of the IBM WebSphere Application Server 6.0 Administration Console application. This application is unique and involves a greater amount of configuration than do other applications. The second subsection describes the configuration of any application protected by Agent for IBM WebSphere Application Server 6.0.

Global Configuration Steps for IBM WebSphere Application Server 6.0

You must perform a variety of procedures to protect the IBM WebSphere Application Server 6.0 Administration Console and the web applications protected by the agent. This agent achieves the goal of protecting both the Administration Console web application and other web applications with the same agent binaries and configuration.

Note –

The tasks of setting the Custom Registry, adding the Access Manager Trust Association Interceptors, and enabling global security, which are all described subsequently in this section, are to be performed once per IBM WebSphere Application Server 6.0 node regardless of how many IBM WebSphere Application Server 6.0 instances exist within that node.

ProcedureTo Set the Custom Registry of IBM WebSphere Application Server 6.0

  1. Start the IBM WebSphere Application Server 6.0 instance.

    The following command is an example of starting an IBM WebSphere Application Server 6.0 instance named host1:

    startServer.bat host1

  2. Log in to the IBM WebSphere Application Server 6.0 Administration Console.

  3. Navigate to the Custom user registry page.

    1. Expand the Security node.

    2. Click Global security.

      A new page opens

    3. Click Custom under User registries.

  4. Set the provider of the custom registry.

    1. In the Custom Registry class name field, replace the existing value with the following value:

      com.sun.identity.agents.websphere.AmAgentUserRegistry

    2. Assign the value for the provider user name.

      Provide the agent profile name as the value of the provider user name.

      For more information, see Creating a J2EE Agent Profile.

    3. Assign the value for the provider password.

      Provide the agent profile password as the value of the provider password.

  5. Save and apply changes to Master configuration.

ProcedureTo Add an Access Manager Trust Association Interceptor to IBM WebSphere Application Server 6.0

This task allows the agent to establish SSO with the protected IBM WebSphere Application Server 6.0 instance.

  1. In the IBM WebSphere Application Server 6.0 Administration Console, navigate to the Interceptors page.

    1. Expand the Security node.

    2. Click Global security.

      A new page opens

    3. Expand the Authentication Mechanisms node.

    4. Click LTPA.

      A new page opens.

    5. Click Trust association link.

    6. Click Interceptors.

  2. Click New.

  3. Name the new Trust Association Interceptor with the following class name:

    com.sun.identity.agents.websphere.AmTrustAssociationInterceptor

  4. Click Apply.

    A new page opens.

  5. Save changes.

    1. Click the Save link.

      A new page opens.

    2. Click the Save button.

  6. Navigate again to the Interceptors page.

    The navigation steps are explained at the beginning of this task description.

  7. Check the Trust Association Enabled checkbox.

  8. Click OK.

  9. Save and apply changes to Master configuration.

ProcedureTo Turn On Global Security of IBM WebSphere Application Server 6.0

  1. In the IBM WebSphere Application Server 6.0 Administration Console, navigate to Global security page.

    1. Expand the Security node.

    2. Click Global security.

      A new page opens.

  2. Turn on global security.

  3. (Optional) Turn on java2.policy.

  4. In the same tab, Active Authentication mechanism, select LTPA.

  5. For Active User Register, select Custom User Registry.

  6. Save and apply changes to Master configuration.

    If you made any mistakes in the configuration prior to this step, this step will fail.

ProcedureTo Deploy the Agent Application

  1. (Conditional) If you have not deployed the agentapp.war file, deploy it as explained in Deploying the Agent Application for J2EE Agents in Policy Agent 2.2.

    This application will trap notifications and perform other housekeeping tasks.

ProcedureTo Grant Access to IBM WebSphere Application Server 6.0 Administration Console

Granting specific Access Manager roles the ability to access the IBM WebSphere Application Server 6.0 Administration Console requires that you change the mapping in the admin-authz.xml file to the appropriate roles.

Two methods are available to you for performing this task. You can use the agentadmin --setGroup command or you can manually edit the file by adding the groups element for every IBM WebSphere Application Server 6.0 role.

Before You Begin

Regardless of the method you use to edit the file, first create a backup file.

  1. Edit the file with the method of your choice as follows:

    • (Option 1) Issue the appropriate type of command depending on the Access Manager version as follows:

      Access Manager 7 Command 
      agentadmin --setGroup administrator id=manager,ou=role,dc=iplanet,dc=com 
C:\WAS60\IBM\WebSphere\AppServer\profiles\default\config\cells\localhostNode01Cell
      Access Manager 6.3 Command 
      agentadmin --setGroup administrator cn=manager,dc=iplanet,dc=com 
C:\WAS60\IBM\WebSphere\AppServer\profiles\default\config\cells\localhostNode01Cell

      Execute this same command for any other IBM WebSphere Application Server 6.0 roles defined in admin-authz.xml, such as configurator, monitor, and operator.

      The --setGroup option of the agentadmin program is an option specifically available in Agent for IBM WebSphere Application Server 6.0. The format of the agentadmincommand using the --setGroup option is as follows:

      agentadmin --setGroup WebSphere-rolename AccessManager-groupname admin-authz.xml-directory
      Note –

      The --setGroup option has a counterpart named --removeGroup, which can be used to remove an Access Manager group name. The following command example illustrates the format of the agentadmin --removeGroup command:

      agentadmin --removeGroup WebSphere-rolename AccessManager-groupname admin-authz.xml-directory

      You could use the --removeGroup option during the uninstallation of the agent. Using the --removeGroup option with the agentadmin program is one method available to you for restoring the admin-authz.xml file to its original state.

      As demonstrated in the preceding agentadmin command examples, the --setGroup option and the --removeGroup option both support the following arguments:

      WebSphere-rolename

      represents an IBM WebSphere Application Server 6.0 role name, such as administrator.

      AccessManager-groupname

      represents an Access Manager group name, such as id=manager,ou=role,dc=iplanet,dc=com for Access Manager 7 or cn=manager,dc=iplanet,dc=com for Access Manager 6.3.

      admin-authz.xml-directory

      represents the directory that contains the admin-authz.xml file.

      This option can be used to set the group name that is authorized to access the IBM WebSphere Application Server 6.0 Administration Console after the agent is installed. The option makes the change in the admin-authz.xml file. The IBM WebSphere Application Server 6.0 role name corresponds to any valid role name in the admin-authz.xml file found within the role element. The Access Manager group name corresponds to Access Manager roles, groups, filtered groups, and such.

      ForAccess Manager 7, the group name is the universal ID (UUID) of the corresponding Access Manager object. For Access Manager 6.3, the group name is the distinguished name (DN) of the user. In a federated environment the group name is the corresponding value of the session attribute that holds the group name. The last argument is the fully qualified path to the admin-authz.xml file used by the IBM WebSphere Application Server 6.0 Administration Console to authorize users. The admin-authz.xml file can be found in the following directory:

      DeployContainer-base/config/cells/Cell-Name
      DeployContainer-base

      represents the directory within which the IBM WebSphere Application Server 6.0 instance was installed.

      Cell-Name

      represents the IBM WebSphere Application Server 6.0 cell protected by the agent.

      This directory contains the server instances protected by the agent. The option does not check the validity of the Access Manager group name.

    • (Option 2) Edit the admin-authz.xml file by adding the groups element for every IBM WebSphere Application Server 6.0 role.

      See Option 1 for information about the Access Manager group name and about the full path to the admin-authz.xml file.

      The following snippets of code show how the changed elements in this file might look depending upon the Access Manager version:

      Code Snippet for Access Manager 7 
      <authorizations xmi:id="RoleAssignmentExt_2" role="SecurityRoleExt_2">
<groups xmi:id="GroupExt_1070109200"  name="id=manager,ou=role,dc=iplanet,dc=com"/>
</authorizations>
      Code Snippet for Access Manager 6.3 
      <authorizations xmi:id="RoleAssignmentExt_2" role="SecurityRoleExt_2">
<groups xmi:id="GroupExt_1070109200"  name="cn=manager,dc=iplanet,dc=com"/>
</authorizations>
      Note –

      The value assigned to xmi:id must be unique. Make similar changes for any other IBM WebSphere Application Server 6.0 role, such as configurator, monitor, and operator.

  2. Stop the IBM WebSphere Application Server 6.0 instance.

ProcedureTo Install the Agent Filter for the IBM WebSphere Application Server 6.0 Administration Console

The procedures that you have performed up to this point enable the Trust Association Interceptor to protect the Administration Console while users log in and establish the correct principal. However, the Trust Association Interceptor cannot trap logout events, enforce URL policies, and such. This filter would allow the enforcement of coarse grained URL policies defined within Access Manager to further control the access to protected resources on the IBM WebSphere Application Server 6.0 Administration Console. Therefore, the agent filter must be inserted into the web.xml file as explained in the following steps to protect the Administration Console. Without the filter element, you can log in to the Administration Console and perform normal operations, but the logout button will not function.

Note –

As explained in this task description, the agent filter should be the last filter executed in sequence. Therefore, ensure that you insert the agent filter after all other filters in the web.xml file.

  1. Change to the following directory:

    DeployContainer-base\systemApps\adminconsole.ear\adminconsole.war\WEB-INF\

    where DeployContainer-base represents the directory within which the IBM WebSphere Application Server 6.0 instance was installed.

  2. Create a back up of the web.xml file.

  3. Insert the agent filter into the file.

    Ensure that the filter that you add is the last filter to be executed in sequence. The following snippet of code shows an excerpt of the web.xml file before the agent filter is added:


    <filter>
     <filter-name>WSCUrlFilter</filter-name>
     <filter-class>com.ibm.ws.console.core.servlet.WSCUrlFilter</filter-class>
</filter>
<filter-mapping>
     <filter-name>WSCUrlFilter</filter-name>
     <servlet-name>action</servlet-name>
</filter-mapping>
<filter-mapping>
	<filter-name>WSCUrlFilter</filter-name>
     <url-pattern>/federatedlogoff</url-pattern>
</filter-mapping>

    The preceding snippet of code might appear as follows after the agent filter has been added:


    filter>
     <filter-name>WSCUrlFilter</filter-name>
     <filter-class>com.ibm.ws.console.core.servlet.WSCUrlFilter</filter-class>
</filter>
<filter>
     <filter-name>Agent</filter-name>
     <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
</filter>

<filter-mapping>
     <filter-name>WSCUrlFilter</filter-name>
     <servlet-name>action</servlet-name>
</filter-mapping>
<filter-mapping>
	<filter-name>WSCUrlFilter</filter-name>
     <url-pattern>/federatedlogoff</url-pattern>
</filter-mapping>

<filter-mapping>
    <filter-name>Agent</filter-name>
    <url-pattern>/*</url-pattern>
 </filter-mapping>

ProcedureTo Allow Access to the IBM WebSphere Application Server 6.0 Administration Console

This task involves creating the corresponding URL policies in the Access Manager Console so that a specific user, group, or role has access to the IBM WebSphere Application Server 6.0 Administration Console application.

  1. Create URL policies that will provide the appropriate subjects with access to the Administration Console application.

    Ensure that you give access to both HTTP and HTTPS based administration URLs.

    For example, you might allow the manager role access to the IBM WebSphere Application Server 6.0 Administration Console by setting the following URL patterns:

    http://host1.subexample.example.com:9060/*
https://host1.subexample.example:9043/*

    This example assumes that the IBM WebSphere Application Server 6.0 Administration Console is running with the HTTP protocol set at port 9060 and with the HTTPS protocol set at 9043. All other changes to the agent configuration to trap logout events have already been configured by the agent installer in J2EE agent AMAgent.properties file. Note that the agent is configured in the most restrictive mode ALL at this point.

ProcedureTo Verify Access to the IBM WebSphere Application Server 6.0 Administration Console

This task involves verifying that the previous tasks were properly performed and that subjects assigned access to the IBM WebSphere Application Server 6.0 Administration Console are indeed able access the console.

  1. Start the IBM WebSphere Application Server 6.0 instance that you just configured.

  2. Run Agent for IBM WebSphere Application Server 6.0 in message mode.

  3. Ensure that users belong to the manager role in Access Manager.

  4. Log in to the IBM WebSphere Application Server 6.0 Administration Console as a user who belongs to the manager role.

  5. If the user is properly redirected to Access Manager, enter the password for any user assigned the manager role in Access Manager.

    If you are allowed access, you should be redirected to the IBM WebSphere Application Server 6.0 Administration Console.

  6. Perform normal operations in the IBM WebSphere Application Server 6.0 Administration Console.

  7. Click logout.

    You should be redirected to the Access Manager Console.

Configuration of Applications Protected by Agent for IBM WebSphere Application Server 6.0

This section describes the configuration necessary for the specific applications that the agent will protect. This configuration involves the installation of the agent filter, which is installed for each deployed application. The agent filter is installed by modifying the deployment descriptor of the application that is going to be protected.

ProcedureTo Install the Agent Filter for the Deployed Application on Agent for IBM WebSphere Application Server 6.0

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 IBM WebSphere Application Server 6.0.

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

  2. Create the necessary backups before proceeding to modify these descriptors.

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

  3. Edit the application's web.xml descriptor as follows:

    1. Set the <DOCTYPE> element as shown in the following code 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">

      IBM WebSphere Application Server 6.0 supports the Java Servlet Specification version 2.4.

      Note that Servlet API version 2.4 is fully backward compatible with version 2.3. Therefore, all existing servlets should work without modification or recompilation. For more information, see, the Sun Java System Application Server Developer's Guide.

    2. Edit the application's web.xml descriptor.

      Add the <filter> elements in the deployment descriptor. Do this by specifying the <filter>, <filter-mapping>, and <dispatcher> elements immediately following the description element of the <web-app> element in the descriptor web.xml. The following code example displays a sample web.xml descriptor with the <filter>, <filter-mapping>, and <dispatcher> elements added. 


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

    If you want to protect an application with J2EE declarative security, refer to 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 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 the application on IBM WebSphere Application Server 6.0.

    Note –

    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.