test

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

Chapter 4 Post-Installation Tasks for the IBM WebSphere Portal Server 6.0 Policy Agent

This chapter describes configuration and other post-installation considerations and tasks as follows:

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

Common Post-Installation Steps for All J2EE Version 2.2 Agents

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

Updating the Agent Profile for Version 2.2 J2EE Agents

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.

ProcedureTo Update the Agent Profile for Version 2.2 J2EE Agents

Before You Begin

Change 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 the 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 the IBM WebSphere Portal Server 6.0 Agent.

  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 the 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 Version 2.2 J2EE Agents

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.

Note –

For IBM WebSphere Application Server and IBM WebSphere Portal Server 6.0 only, the agentapp.extension must be bound to both listening ports used by the WebSphere Administration Server instance and the WebSphere Portal Server instance.

For example, to bind the agentapp.extension to both listening ports:

  1. From the Administration console, deploy agentapp.extension to the virtual host admin_host.

  2. In the Administration console:

    1. Click Environment, Virtual Hosts, and then admin_host.

    2. Select Host Aliases and then click New.

    3. Specify * in the Host Name field and 10038 in the Port field.

    4. Click Apply, save link, and then Save.

      In this example, 10038 is the Portal Server instance's port.

  3. Restart both the Administration server instance and the Portal Server instance.

Post-Installation Steps Specific to the IBM WebSphere Portal Server 6.0 Agent

After you have installed the IBM WebSphere Portal Server 6.0 agent 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 tasks:

Adding an Access Manager Trust Association Interceptor to IBM WebSphere Portal Server 6.0

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

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.

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

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

  2. Start the Administration 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 6.0 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 the changes:

    1. Click Save.

      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 the Master configuration.

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

    The Policy Agent Trust Association Interceptor is now installed.

Changing the Logout Link Actions for IBM WebSphere Portal Server 6.0

You can change the Logout actions within IBM WebSphere Portal Server 6.0 to provide a seamless user experience with single sign-on (SSO) using Access Manager.

ProcedureTo Change the Logout Link Actions for IBM WebSphere Portal Server 6.0

  1. Ensure that the IBM WebSphere Application Server and IBM WebSphere Portal Server 6.0 instances are running.

  2. Backup the following file:

    WPS-base/PortalServer/config/properties/ConfigService.properties

    where WPS-base represents the directory where IBM WebSphere Portal Server 6.0 was installed.

  3. Modify the WPS-base/PortalServer/config/properties/ConfigService.properties file as follows:

    1. Set redirect.logout to true.

    2. Set redirect.logout.ssl to true or false, depending upon the environment.

    3. Set redirect.logout.url to the Access Manager logout URL (AMlogout-URL).

      where AMlogout-URL represents the Access Manager logout URL. For example:


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

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

    Important: Remove the comment sign (#) from the above changed lines and then save the file.

  4. Run the following portal configuration task:


    WPS-base/PortalServer/config/WPSconfig.sh update-properties

  5. If you are running WebSphere Portal Server in a cluster, replicate your changes to the cluster.

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

Adding the Agent Filter to the IBM WebSphere Application Server 6.0 Administration Console

This required task more tightly integrates the IBM WebSphere Application Server 6.0 Administration Console with the Access Manager environment. This task is required only once for the IBM WebSphere Application Server 6.0 Administration instance (typically server1) where the Administration Console is installed.

The IBM WebSphere Portal Server 6.0 agent provides a servlet filter that can be added to the IBM WebSphere Application Server 6.0 Administration Console. 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 Administration Console. The following steps detail how this filter can be installed.

ProcedureTo Add the Agent Filter to the IBM WebSphere Application Server 6.0 Administration Console

  1. Ensure that the Administration instance of IBM WebSphere Application Server is stopped.

  2. Locate the adminconsole/WEB-INF/web.xml file, which contains the deployment descriptors for the IBM WebSphere 6.0 Administration Console.

    The path to this web.xml file is:

    WAS-base/AppServer/systemApps/adminconsole.ear/adminconsole.war/WEB-INF/

    where WAS-base represents the directory where IBM WebSphere Application Server 6.0 was installed.

  3. Backup the web.xml file.

    Because you will modify the deployment descriptor in the next step, creating a backup file at this point is important, especially if you need to uninstall the agent in the future.

  4. Edit the web.xml file, as follows:

    <display-name>adminconsole</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>

Adding the Agent Filter to the IBM WebSphere Portal Server 6.0 Application

This required task integrates the IBM WebSphere Portal Server 6.0 instance with the Access Manager environment.

Note –

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

The IBM WebSphere Portal Server 6.0 agent provides a servlet filter that can be added to the IBM WebSphere Portal Server 6.0 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 6.0 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.

ProcedureTo Add the Agent Filter to the IBM WebSphere Portal Server 6.0 Application

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

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

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

    • WAS-base/AppServer/profiles/wp_profile/installedApps/
Cell-Name/wps.ear/wps.war/WEB-INF
    • WAS-base/AppServer/profiles/wp_profile/config/cells/
Cell-Name/applications/wps.ear/deployments/wps/wps.war/WEB-INF

    where:

    WAS-base represents the directory where IBM WebSphere Application Server 6.0 was installed.

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

  3. Backup the two web.xml files before modifying the deployment descriptors.

    Since you will modify the deployment descriptor in the next step, creating backup files at this point is important, especially if you need to uninstall the agent in the future.

  4. Edit both of the web.xml files referred to in this task, as follows:


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

Creating the Administrative User IDs in Access Manager for WebSphere Application Server and WebSphere Portal Server

When Websphere Portal Server 6.0 is installed, two administrative user IDs should have been created in the WebSphere Portal:

Therefore, you should create the same user IDs, wasadmin and wpsadmin, in Access Manager. These names are used to authenticate to Access Manager and to access the WebSphere Administration Console and WebSphere Portal Server as the respective administrator after the agents are installed and configured.

Conditional Post-Installation Steps for Version 2.2 J2EE Agents

The following steps described in this section might be required, depending on your site's specific deployment:

Creating the Necessary URL Policies

If the agent is installed and configured to operate in the URL_POLICY or ALL mode, the appropriate URL policies must be created. For example, WebSphere Application Server with Administration Console is listening on ports 10001 (http) and 10003 (https), respectively, and WebSphere Portal Server is listening on port 10038 (http), create the following polices for the WebSphere Administrative user IDs (wasadmin and wpsadmin) to allow them to access the WebSphere Administration Console and Portal Server URLs:

http://myhost.mydomain.com:10001/*
https://myhost.mydomain.com:10003/*
http://myhost.mydomain.com:10038/*

Note: This example assumes that http://myhost.mydomain.com:10001/ibm/console is the Administration console URL and http://myhost.mydomain.com:10038/wps/myportal is the Portal Server URL.

If the policies are not defined and the agent is configured to operate in the URL_POLICY or ALL mode, then no user is allowed access to the IBM WebSphere Application Server and Portal Server 6.0 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.

Installing and Configuring the WebSphere Portal 6.0 Agent With Access Manager 6 2005Q1 (6.3)

To use this agent with Access Manager 6.3, perform these steps after the agent installation.

ProcedureTo Install and Configure the WebSphere Portal 6.0 Agent With Access Manager 6 2005Q1 (6.3)

  1. Change to the PolicyAgent-base/lib directory.

  2. Download the amclientsdk63.jar and fmclientsdk.jar files to the PolicyAgent-base/lib directory from the OpenSSO project site:

    http://opensso.dev.java.net/public/use/stablebuilds.html

  3. Change to the WAS-base/AppServer/lib/ext directory.

    where WAS-base represents the directory where IBM WebSphere Application Server 6.0 was installed.

  4. Copy the downloaded amclientsdk63.jar and fmclientsdk.jar files into the WAS-base/AppServer/lib/ext directory and remove the famclientsdk.jar file.

  5. Restart all WebSphere server instances to make these changes take effect.