Chapter 4 Post-Installation Tasks of Policy Agent 2.2 for IBM WebSphere Portal Server 5.1.0.2

This chapter describes 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 IBM WebSphere Portal Server 5.1.0.2

• 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 requirements as explained in Chapter 5, Managing Policy Agent 2.2 for IBM WebSphere Portal Server 5.1.0.2.

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, see Preparing to Install Agent for IBM WebSphere Portal Server 5.1.0.2.

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 must 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 the deployment container, deploy this application using Application Context Path as the URI specified during agent installation.

Post-Installation Steps Specific to Agent for IBM WebSphere Portal Server 5.1.0.2

Once you have installed Policy Agent 2.2 for IBM WebSphere Portal Server 5.1.0.2 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.

A variety of configuration tasks are described in this section.

To Add an Access Manager Trust Association Interceptor to IBM WebSphere Portal Server 5.1.0.2

This task must be performed once per IBM WebSphere Application Server node regardless of how many IBM WebSphere Application Server instances exist within that node.

This task allows the agent to establish SSO with the protected IBM WebSphere Portal Server 5.1.0.2 instance.

1. Ensure that all instances of the underlying IBM WebSphere Application Server are stopped.

2. Start the instance of IBM WebSphere Application Server on which the Administration Console is deployed.

   Typically this instance is named server1

3. Log in to the IBM WebSphere Portal Server 5.1.0.2 Administration Console.

4. Navigate to the Interceptors page.

   1. Expand the Security node.

   2. Expand the Authentication Mechanisms node.

   3. Click LTPA.

      A new page appears.

   4. Click the Trust association link.

   5. Click Interceptors.

5. Click New.

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

   com.sun.identity.agents.websphere.AmTrustAssociationInterceptor

7. Click Apply.

   A new page opens.

8. Save changes.

   1. Click the Save link.

      A new page opens.

   2. Click the Save button.

9. Navigate again to the Interceptors page.

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

10. Check the Trust Association Enabled checkbox.

11. Click OK.

12. Save and apply changes to Master configuration.

13. Restart all server instances as necessary including the instance on which IBM WebSphere Portal Server 5.1.0.2 is deployed.

    The Policy Agent Trust Association Interceptor is now installed.

To Change the Login and Logout Link Actions for IBM WebSphere Portal Server 5.1.0.2

The Login and Logout actions within IBM WebSphere Portal Server 5.1.0.2 can be changed to better provide a seamless user experience with Single Sign-On using Access Manager. This can be achieved by implementing the steps in this task description.

1. Ensure that the IBM WebSphere Portal Server 5.1.0.2 instance is shut down.

2. Create backups of the applicable ToolBarInclude.jsp files.

   In this scenario, the applicable ToolBarInclude.jsp files are available within the following directory:

   WAS-base/installedApps/node_name/wps.ear/wps.war/themes/html/

   where WAS-base represents the directory within which the IBM WebSphere Portal Server 5.1.0.2 instance was installed. Notice that this task refers to both a WAS-base directory and a WPS-base directory.

3. Modify each applicable ToolBarInclude.jsp file.

   For this task, modify each file as follows:

   Replace the href value associated with the Login link with the following value:.

   <%= wpsBaseURL %>/myportal

   The following example shows modifications that can be made to the ToolBarInclude.jsp file to change the login action:

   <%-- login button --%> <%-- uncomment to allow log in via screen --%> <%-- <wps:if loggedIn="no" notScreen="Login"> <td class="wpsToolBar" valign="middle" nowrap> <a class="wpsToolBarLink" href='<%=wpsBaseURL%>/myportal'> <wps:text key="link.login" bundle="nls.engine"/> </a> </td> </wps:if> --%> <%--comment this to allow login via screen --%> <wps:if loggedIn="no" notSelection="wps.Login" > <wps:urlGeneration contentNode="wps.Login" portletWindowState="Normal"> <td class="wpsToolBar" valign="middle" nowrap> <a href='<%=wpsBaseURL%>/myportal' class="wpsToolBarLink"> <wps:text key="link.login" bundle="nls.engine"/> </a> </td> </wps:urlGeneration> </wps:if>

   For complete details on how best to implement the preceding modification, see documentation for IBM WebSphere Portal Server 5.1.0.2.

4. Create backups of the following file:

   WPS-base/shared/app/config/services/ConfigService.properties

   where WPS-base represents the directory within which the IBM WebSphere Portal Server 5.1.0.2 instance was installed.

5. Modify the ConfigService.properties file as follows:

   redirect.logout

   Set the value to true.

   redirect.logout.ssl

   Set the value to true or false, depending upon the environment.

   redirect.logout.url

   Set the value to the Access Manager logout URL (AMlogout-URL).

   where AMlogout-URL represents the Access Manager logout URL. The following is a conceivable logout URL:

   http://amhost.domain.com:AMport/amserver/UI/Logout

   where AMport represents the port number of the Access Manager host.

6. Restart the IBM WebSphere Portal Server 5.1.0.2 instance for these changes to take effect.

To Add the Agent Filter to the IBM WebSphere Portal Server 5.1.0.2 Application

This required task more tightly integrates the IBM WebSphere Portal Server 5.1.0.2 instance with the Access Manager environment.

This task is only required once per IBM WebSphere Portal Server 5.1.0.2 instance for a given host.

Agent for IBM WebSphere Portal Server 5.1.0.2 provides a servlet filter that can be added to the IBM WebSphere Portal Server 5.1.0.2 application. This filter allows the enforcement of coarse grained URL policies defined within Access Manager to further control the access to protected resources on the IBM WebSphere Portal Server 5.1.0.2 instance. The filter can also be configured to provide additional personalization information in the form of HTTP Headers, cookies, or HTTP Request Attributes that can be used to further enhance the functionality of protected components. The following steps detail how this filter can be installed.

1. Ensure that the instance of IBM WebSphere Application Server on which the IBM WebSphere Portal Server 5.1.0.2 is deployed is stopped.

2. Locate the wps.war/WEB-INF/web.xml file that contains the deployment descriptors for IBM WebSphere Portal Server 5.1.0.2.

   The IBM WebSphere Application Server runtime can read this file from either of the following directories:

   • WPS-base/installedApps/Cell-Name/wps.ear/wps.war/WEB-INF

   • WPS-base/config/cells/Cell-Name/applications/wps.ear/deployments/wps/wps.war/WEB-INF

   WPS-base

   represents the directory within which the IBM WebSphere Portal Server 5.1.0.2 instance was installed.

   Cell-Name

   represents the IBM WebSphere Portal Server 5.1.0.2 cell protected by the agent.

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

4. Edit both of the web.xml files referred to in this task.

   The two web.xml files should be edited as follows:

   <web-app id="IBM_WPS"> <display-name>WebSphere Portal Server</display-name> <filter id="Filter_PolicyAgent"> <filter-name>Policy Agent</filter-name> <filter-class> com.sun.identity.agents.filter.AmAgentFilter </filter-class> </filter> ... //other filter definitions <filter-mapping id="FilterMapping_PolicyAgent"> <filter-name>Policy Agent</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>... //other filter mappings </web-app>

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.

Combining J2EE Agents With Access Manager

This is a conditional post-installation step that must be performed when the J2EE agent is installed on the same deployment container that hosts Access Manager. Note that Access Manager should be installed prior to the agent being installed. Therefore, the order to install these servers on the same machine is as follows:

1. Deployment container

2. Access Manager

3. J2EE agent

This type of deployment not only requires that you perform a post-installation configuration step as described in the next subsection, this type of deployment also changes where J2EE agent debug log files are stored. For more information, see Locating the J2EE Agent Debug Log Files for Policy Agent 2.2.

Configuring the J2EE Agent in Policy Agent 2.2 to Use the Remote Client SDK of Access Manager

After the J2EE agent is installed, it must use the Remote Client SDK provided by the Access Manager installation.

Modify the Access Manager configuration file, AMConfig.properties, by specifically adding the following entry, which contains the agent configuration location information:

com.sun.identity.agents.config.location =
 PolicyAgent-base/AgentInstance-Dir/config/AMAgent.properties

Locating the J2EE Agent Debug Log Files for Policy Agent 2.2

Installing the J2EE agent and Access Manager on the same deployment container changes the file to which the J2EE agent debug log entries are written. This change occurs because the location of the debug files is set in the properties configuration file. In this type of deployment, two configuration files exist on the same host. However, the Access Manager AMConfig.properties configuration file takes precedence over the J2EE agent AMAgent.properties configuration file.

When the J2EE agent and the Access Manager are installed on separate hosts the debug information is stored in the following directory:

PolicyAgent-base/AgentInstance-Dir/logs/debug

However, when the J2EE agent and Access Manager are installed on the same host, the agent-specific debug information is stored in the following Access Manager directory:

/var/opt/SUNWam/debug