Chapter 4 Post-Installation Tasks for the IBM WebSphere Application Server 6.1 Policy Agent

This chapter describes post-installation tasks for the IBM WebSphere Application Server 6.1 agent, including:

• Common Post-Installation Tasks for All Version 2.2 J2EE Agents

• Post-Installation Tasks Specific to the WebSphere Application Server 6.1 Agent

• Conditional Post-Installation Task for Version 2.2 J2EE Policy Agents

After completing the applicable tasks described in this chapter, perform the tasks to configure the agent to your site's specific requirements as explained in Chapter 5, Managing Policy Agent 2.2 for WebSphere Application Server 6.1.

Common Post-Installation Tasks for All Version 2.2 J2EE Agents

The following task applies to all J2EE agents:

• Deploying the Agent Application for Version 2.2 J2EE Agents

• Updating the Agent Profile for Version 2.2 J2EE Agents

Deploying the Agent Application for Version 2.2 J2EE Agents

The agent application is a housekeeping application used by the agent for notifications and other internal functionality. This application is bundled with the agent 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 the deployment container, deploy this application using Application Context Path as the URI specified during agent installation.

Updating the Agent Profile for Version 2.2 J2EE Agents

Updating the agent profile is optional. You create the agent profile in the Access Manager Console before you install the agent, as described in Creating a J2EE Agent Profile. After you install the agent, you can update the agent profile at anytime, if you wish. If you do update the agent profile in the Access Manager Console, you must then re-configure the agent, as described in this section.

To Update the Agent Profile for Version 2.2 J2EE Agents

Before You Begin

Update the agent profile in Access Manager using the 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 theAccess 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, see Preparing to Install Agent for WebSphere Application Server 6.1.

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 theAccess 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 deployment container.

   You must restart the container because the properties that you edited in this task are not hot-swap enabled.

Post-Installation Tasks Specific to the WebSphere Application Server 6.1 Agent

After you install the WebSphere Application Server 6.1 agent and perform the post-installation steps that apply to all version 2.2 J2EE agents, complete the following agent-specific tasks:

• Creating the Agent Profile User and Role, WebSphere Primary Administrative User, and WebSphere Administrative Role

• Global Configuration Tasks for WebSphere Application Server 6.1

• Configuring Applications Protected by the WebSphere Application Server 6.1 Agent

For more information about the concepts described in this section, see High-Level Architecture of Agent for WebSphere Application Server 6.1.

Creating the Agent Profile User and Role, WebSphere Primary Administrative User, and WebSphere Administrative Role

Important: Perform the following tasks before you perform any other post-installation tasks for the WebSphere Application Server 6.1 agent:

• Creating a New J2EE Agent Profile User

• Creating a New J2EE Agent Profile Role and Assign the Role to the Agent Profile User

• Assigning Read Access to the Agent Profile Role

• Creating the Primary Administrative User in Access Manager

• Creating the WebSphere Administrative Role in Access Manager

• Editing the AMConfig.properties File to Get a Non-Expiring SSO Token for the New Agent Profile User's SSO Session

Creating a New J2EE Agent Profile User

The process to create an agent profile user for the WebSphere Application Server 6.1agent is different than the process for other J2EE agents. If you have already created an agent profile user in the pre-installation tasks as described in Creating a J2EE Agent Profile, you must remove that user from the Access Manager Console and then recreate the agent profile user using the same user name and password.

Use the new agent profile user to stop WebSphere Application Server 6.1 after WebSphere global security is turned on.

To Create a New J2EE Agent Profile User

1. Login to the Access Manager Console.

2. With the Access Control tab selected, click the name of the realm for which you would like to create the agent profile.

3. Select the Subjects tab.

4. Make sure you are in the User tab.

5. Click New and enter values for the following fields:

   • ID. Enter the name or identity of the agent. This name should be the same name you used in the pre-installation task. For example: agentprofileuser.

   • Password. Enter and then confirm the agent password.

     This password should be the same password you used in the pre-installation task.

   • User Status. Set the device status of the agent to Active.

   • Any other required fields.

6. Click Create.

Creating a New J2EE Agent Profile Role and Assign the Role to the Agent Profile User

This new internal role is specifically for the agent profile user for the WebSphere Application Server 6.1 agent. This role will allow the agent profile user to read user attributes in the user repository.

To Create a New J2EE Agent Profile Role and Assign the Role to the Agent Profile User

1. Login to the Access Manager Console.

2. With the Access Control tab selected, click the name of the realm for which you would like to create the agent profile role.

3. Select the Subjects tab and then click the Role tab.

4. Click New and then enter a value for the agent profile role. For example: agentprofilerole

5. Click Create.

6. Under the Role tab, click the agent profile role.

7. On the new page, click the User tab.

8. Select the agent profile user (such as agentprofileuser) under the Available field.

9. Click Add and then Save.

Assigning Read Access to the Agent Profile Role

To Assign Read Access to the Agent Profile Role

1. Login to the Access Manager Console.

2. With the Access Control tab selected, click the name of the realm where your agent profile role was created.

3. Click the Privileges tab.

4. Find and click the agent profile role. For example: agentprofilerole

5. On the new page, check the “Read only access to data stores” checkbox.

6. Click Save.

Creating the Primary Administrative User in Access Manager

This user will be able to login to the WebSphere Administration Console when global security is enabled.

To Create the Primary Administrative User in Access Manager

1. Login to the Access Manager Console.

2. With the Access Control tab selected, click the name of the realm for which you would like to create an agent profile.

3. Select the Subjects tab.

4. Make sure you are in the User tab.

5. Click New and enter values for the following fields:

   • ID. Enter the name or identity of the user. For example: wasadmin

   • Password. Enter and confirm the user password.

   • User Status. Set the device status of the agent to Active.

   • Any other required fields.

6. Click Create.

Creating the WebSphere Administrative Role in Access Manager

Any user with this role, in addition to the primary administrative user, will be able to login to the WebSphere Administration Console.

To Create the WebSphere Administrative Role in Access Manager

1. Login to the Access Manager Console.

2. With the Access Control tab selected, click the name of the realm for which you would like to create an agent profile role.

3. Select the Subjects tab and then click the Role tab.

4. Click New and enter the value for the WebSphere administrative role. For example: wasadminrole

   Important: Use all lowercase characters for the role name; otherwise, WebSphere might not recognize the name.

5. Click Create.

6. On the returned page, click the WebSphere administrative role under the Role tab. For example: wasadminrole

7. Click the User tab.

8. Select the agent profile user (for example: agentprofileuser) and other users who will be able to login into the WebSphere Administration Console.

9. Click Add and then Save.

Editing the AMConfig.properties File to Get a Non-Expiring SSO Token for the New Agent Profile User's SSO Session

To get a non-expiring SSO token for the agent's self authentication to the Access Manager server, you must set the com.sun.identity.authentication.special.users property in the AMConfig.properties file.

To Get a Non-Expiring SSO Token

1. In the AMConfig.properties file for the Access Manager server, edit the following property to include the distinguished name (DN) of the agent profile user. Use the legacy SDK DN and not the universal UID of the user. For example:

   com.sun.identity.authentication.special.users= 
   cn=dsameuser,ou=DSAME Users,dc=sun, dc=com|cn=amService-UrlAccessAgent,ou=DSAME Users, 
   dc=sun,dc=com |uid=dmgr,ou=people,dc=sun,dc=com|uid=agentprofileuser, 
   ou=people,dc=sun,dc=com  

   To find the DN of the user, use ldapsearch with the ou=people,ROOT_SUFFIX base and (|(uid=agentprofileuser)(cn=agentprofileuser)) filter.

2. After you edit the AMConfig.properties file, restart the Access Manager server.

Next Steps

In a multiple server deployment, you must set the com.sun.identity.authentication.special.users property in the AMConfig.properties file for each Access Manager server in the deployment.

Global Configuration Tasks for WebSphere Application Server 6.1

You must perform specific procedures to protect the WebSphere Application Server 6.1 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.

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 WebSphere Application Server 6.1 node regardless of how many WebSphere Application Server 6.1 instances exist within that node.

Setting the Custom Registry of WebSphere Application Server 6.1

To Set the Custom Registry of WebSphere Application Server 6.1

1. Start the WebSphere Application Server 6.1 instance.

   For example, the following command starts a WebSphere Application Server 6.1 instance named host1:

   startServer.bat host1

2. Log in to the WebSphere Application Server 6.1 Administration Console.

3. Navigate to the Custom user registry page.

   1. Expand the Security node.

   2. Click “Secure administration, applications, and infrastructure”. A new page opens.

   3. Under the Available realm definitions field, select Standalone custom registry.

   4. Click the Set as current button.

   5. Click the Configure button. A new page opens.

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. In the “Primary administrative user name” field, enter the administrative user name, which was previously created in Access Manager. For example: wasadmin

   3. For the Server user identity option:

      • In environments that contain only version 6.1 or later nodes, select “Automatically generated server identity”.

      • In environments whose cell contains version 5.x or 6.0.x nodes, select “Server identity that is stored in the repository”. Enter the agent profile user name (such as agentprofileuser) in the “Server user ID or administrative user on a Version 6.0.x node” field, and enter the agent profile user password in the “Password” field.

   4. Click OK. The page returns to “Secure administration, applications, and infrastructure”.

   5. Click the “Save directly to the master configuration” link.

Adding an Access Manager Trust Association Interceptor to WebSphere Application Server 6.1

This task allows the agent to establish single sign-on (SSO) with the protected WebSphere Application Server 6.1 instance.

To Add an Access Manager Trust Association Interceptor to WebSphere Application Server 6.1

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

   1. Expand the Security node.

   2. Click “Secure administration, applications, and infrastructure”. A new page opens.

   3. Under the “Authentication” option, expand “Web security”.

   4. Click “Trust association”. The “Trust association” page opens.

   5. Click the Interceptors link. The Interceptors page opens.

2. Click New. A new page opens.

3. In the “Interceptor class name” field, enter:

   com.sun.identity.agents.websphere.AmTrustAssociationInterceptor

4. Click OK. The browser returns to the Interceptor page.

5. Click “Save directly to the master configuration”.

6. Navigate again to the Interceptors page by clicking the “Trust association” link at the top of the page.

7. Check the “Enable trust association” checkbox.

8. Click OK. The page returns to “Secure administration, applications, and infrastructure”.

9. Click “Save directly to the master configuration”.

Turning On Global Security for WebSphere Application Server 6.1

To Turn On Global Security for WebSphere Application Server 6.1

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

   1. Expand the Security node.

   2. Click “Secure administration, applications, and infrastructure”. A new page opens.

2. Check the “Enable administrative security” checkbox.

3. Make sure that “Enable application security” is also checked.

4. Optionally, enable “Java 2 security” on the same page.

5. Click Apply.

6. Click “Save directly to the master configuration”.

Granting Access to the WebSphere Application Server 6.1 Administration Console

To Grant Access to the WebSphere Application Server 6.1 Administration Console

1. From the WebSphere Administrator console, expand the Users and Groups node.

2. Click “Administrative Group Roles”. A new page opens.

3. Click the Add button. A new page opens.

   1. In the field “Group name” field, enter wasadminrole, which was defined earlier.

   2. In the “Role(s)” field, select “Administrator”.

   3. Click OK and return to the “Administrative Group Roles” page.

4. Click “Save directly to the master configuration”.

Editing the AMAgent.properties File

After the agent installation, edit the following property in the AMAgent.properties file:

From:

com.sun.identity.agents.config.logout.uri[ibm/console] = /ibm/console/logoff.do

To:

com.sun.identity.agents.config.logout.uri[ibm/console] = /ibm/console/logout.do

Deploying the Agent Application

If you have not deployed the agent application, deploy the agentapp.war file as described in Deploying the Agent Application for Version 2.2 J2EE Agents. This application will trap notifications and perform other housekeeping tasks.

Installing the Agent Filter for the WebSphere Application Server 6.1 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. The agent filter allows the enforcement of coarse grained URL policies defined within Access Manager to further control the access to protected resources on the WebSphere Application Server 6.1 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.

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.

To Install the Agent Filter for the WebSphere Application Server 6.1 Administration Console

1. Change to the following directory:

   DeployContainer-base/profiles/profile name/config/cells/cell
   name/applications/isclite.ear/deployments/isclite/isclite.war/WEB-INF/

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

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

3. Insert the agent filter into the file.

   Ensure that the agent filter that you add is the last filter to be executed in sequence. The example 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 example shows the agent filter in bold text:

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

Allowing Access to the WebSphere Application Server 6.1 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 WebSphere Application Server 6.1 Administration Console.

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

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

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

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

In this example, the WebSphere Application Server 6.1 Administration Console is running with the HTTP protocol set at port 9060 and 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 the AMAgent.properties file. Note that the agent is configured in the most restrictive mode ALL at this point.

Verifying Access to the WebSphere Application Server 6.1 Administration Console

This task involves verifying that the previous tasks were performed properly and that the subjects assigned access to the WebSphere Application Server 6.1 Administration Console can access the console.

To Verify Access to the WebSphere Application Server 6.1 Administration Console

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

2. Run the WebSphere Application Server 6.1 agent in message mode.

3. Log in to the WebSphere Application Server 6.1 Administration Console as a user who belongs to the WebSphere administrative role. For example: wasadminrole

4. If the user is properly redirected to Access Manager, enter the user name and password for any user assigned the wasadminrole role in Access Manager.

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

5. Perform normal operations in the WebSphere Application Server 6.1 Administration Console.

6. Click logout.

   You should be redirected to the Access Manager Console.

Configuring Applications Protected by the WebSphere Application Server 6.1 Agent

This section describes the configuration necessary for the specific applications that the agent will protect, including Installing the Agent Filter for a Deployed Application on the WebSphere Application Server 6.1 Agent.

Installing the Agent Filter for a Deployed Application on the WebSphere Application Server 6.1 Agent

The following task explain how to install the agent filter for the application you want the agent to protect. Install the agent filter for each deployed application by modifying the deployment descriptor of the application that is going to be protected.

To Install the Agent Filter for the Deployed Application on the WebSphere Application Server 6.1 Agent

1. To install the agent filter, ensure that the application is not currently deployed on WebSphere Application Server 6.1.

   If it is currently deployed, remove it before continuing.

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 is important.

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

   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: WebSphere Application Server 6.1 supports the Java Servlet Specification version 2.4. Because Servlet API version 2.4 is backward compatible with version 2.3, 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 by specifying the <filter>, <filter-mapping>, and <dispatcher> elements immediately following the description element of the <web-app> element in the web.xml descriptor. The following example shows 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>

   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 not a complete 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 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 WebSphere Application Server 6.1.

   ---

   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 by issuing the agentadmin --getUuid command. For more information, see agentadmin --getUuid.

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

   ---

Conditional Post-Installation Task for Version 2.2 J2EE Policy Agents

The tasks are conditional for the WebSphere Application Server 6.1 agent, depending on your site's specific deployment:

• Updating the Agent Profile for Version 2.2 J2EE Agents

• Creating the Necessary URL Policies

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 WebSphere Application Server 6.1 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 WebSphere Application Server 6.1 resources. For information about creating these policies using the Access Manager Console or command-line utilities, see the Sun Java System Access Manager 7.1 Administration Guide.