Skip to ContentSun and Oracle Channel Sun How to Buy Log In

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

Contained Within

Sun Java System Access Manager Policy Agent 2.2

Find More Documentation

Featured Support Resources

Download this book in PDF (1296 KB)

Previous: 3. Installing Policy Agent 2.2 for IBM WebSphere Application Server 5.1.1
Next: 5. Managing Policy Agent 2.2 for IBM WebSphere Application Server 5.1.1

Chapter 4 Post-Installation Tasks of Policy Agent 2.2 for IBM WebSphere Application Server 5.1.1

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 Application Server 5.1.1.

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.

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, seePreparing to Install Agent for IBM WebSphere Application Server 5.1.1.

In the command line, issue the agentadmin --encrypt command to encrypt the new password.

For more information on this command, see agentadmin --encrypt.

Access the J2EE agent AMAgent.properties configuration file at the following location:
```
PolicyAgent-base/AgentInstance-Dir/config
```

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.

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.

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 Application Server 5.1.1

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

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 5.1.1 that the agent will protect. The first subsection describes the configuration of the IBM WebSphere Application Server 5.1.1 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 5.1.1.

Global Configuration Steps for IBM WebSphere Application Server 5.1.1

You must perform a variety of procedures to protect the IBM WebSphere Application Server 5.1.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.

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

To Set the Custom Registry of IBM WebSphere Application Server 5.1.1

Start the IBM WebSphere Application Server 5.1.1 instance.

The following command is an example of starting an IBM WebSphere Application Server 5.1.1 instance named host1:
```
startServer.bat host1
```

Navigate to the Custom user registry page.
1. Expand the Security node.
2. Expand the User Registries node.
3. Click Custom.
  
  A new page opens.

Set the provider of the custom registry.
1. In the Custom Registry classname 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.

Save and apply changes to Master configuration.

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

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

In the IBM WebSphere Application Server 5.1.1 Administration Console, 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.

Click New.

Name the new Trust Association Interceptor with the following class name:
```
com.sun.identity.agents.websphere.AmTrustAssociationInterceptor
```

Click Apply.

A new page opens.

Save changes.
1. Click the Save link.
  
  A new page opens.
2. Click the Save button.

Navigate again to the Interceptors page.

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

Check the Trust Association Enabled checkbox.

Click OK.

Save and apply changes to Master configuration.

To Turn On Global Security of IBM WebSphere Application Server 5.1.1

In the IBM WebSphere Application Server 5.1.1 Administration Console, navigate to Global security page.
1. Expand the Security node.
2. Click Global security.
  
  A new page opens.

Turn on global security.

(Optional) Turn on java2.policy.

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

For Active User Register, select Custom User Registry.

Save and apply changes to Master configuration.

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

To Deploy the Agent Application

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

To Grant Access to IBM WebSphere Application Server 5.1.1 Administration Console

Granting specific Access Manager roles the ability to access the IBM WebSphere Application Server 5.1.1 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 5.1.1 role.

Before You Begin

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

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 
/opt/WebSphere/AppServer/config/cells/hostname/nodes/hostname
```
  Access Manager 6.3 Command
```
agentadmin --setGroup administrator cn=manager,dc=iplanet,dc=com 
/opt/WebSphere/AppServer/config/cells/hostname/nodes/hostname
```
  where hostname represents the host name of the machine on which the IBM WebSphere Application Server 5.1.1 instance is installed.
  
  Execute the same command for any other IBM WebSphere Application Server 5.1.1 roles defined in admin-authz.xml, such as configurator, monitor, and operator.
  
  The --setGroup option of the agentadmin program is an option specifically available for IBM WebSphere Application Server. The format of the agentadmin command 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 5.1.1 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 5.1.1 Administration Console after the agent is installed. The option makes the change in the admin-authz.xml file. The IBM WebSphere Application Server 5.1.1 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.
  
  For Access 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 5.1.1 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 5.1.1 instance was installed.
  
  Cell-Name
  
  represents the IBM WebSphere Application Server 5.1.1 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 5.1.1 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 5.1.1 role, such as configurator, monitor, and operator.

Stop the IBM WebSphere Application Server 5.1.1 instance.

To Install the Agent Filter for the IBM WebSphere Application Server 5.1.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. 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 5.1.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.

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.

Change to the following directory:
```
DeployContainer-base/config/cells/hostname/applications/adminconsole.ear/deployments
/adminconsole/adminconsole.war/WEB-INF
```
DeployContainer-base

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

hostname

represents the host name of the machine on which the IBM WebSphere Application Server 5.1.1 instance is installed.

Create a back up of the web.xml file.

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:

<web-app id="WebApp_1">
<display-name>adminconsole</display-name>
<listener id="Listener_1138486037387">
<listener-class>com.ibm.ws.console.appmanagement.SessionListener</liste
er-class>
</listener>...

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

<web-app id="WebApp_1">
<display-name>adminconsole</display-name>
<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>
</filter-mapping>
<listener id="Listener_1138486037387">
<listener-class>com.ibm.ws.console.appmanagement.SessionListener</listener-class>
</listener>

To Allow Access to the IBM WebSphere Application Server 5.1.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 IBM WebSphere Application Server 5.1.1 Administration Console application.

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

To Verify Access to the IBM WebSphere Application Server 5.1.1 Administration Console

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

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

Run Agent for IBM WebSphere Application Server 5.1.1 in message mode.

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

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 5.1.1 Administration Console.

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

Click logout.

You should be redirected to the Access Manager Console.

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

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.

To Install the Agent Filter for the Deployed Application on Agent for IBM WebSphere Application Server 5.1.1

The following steps explain how to install the agent filter for the application you want the agent to protect:

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

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

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.

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

The filters were introduced in Servlet Specification 2.3. For more information about this specification, see http://jcp.org/aboutJava/communityprocess/first/jsr053/index.html.

The <DOCTYPE> element of the web.xml descriptor must be changed to reflect that the deployment descriptor is, at minimum, a Servlet 2.3 compliant deployment descriptor. To reflect this compliance perform the following substeps.

Set the <DOCTYPE> element as follows:

<!DOCTYPE web-app PUBLIC 
"-//Sun Microsystems, Inc.//DTD Web Application2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">

Add the <filter> elements in the deployment descriptor by specifying the <filter> and the <filter-mapping> elements immediately following the description element of the <web-app> element in the descriptor web.xml.

The following is a sample web.xml descriptor with the <filter> and the <filter-mapping> elements added:

<web-app>
   
   <filter>
     <filter-name>Agent</filter-name>
     <display-name>Agent</display-name>
     <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
   </filter>
   <filter-mapping>
     <filter-name>Agent</filter-name>
     <url-pattern>/*</url-pattern>
   </filter-mapping>
   ...
</web-app>

Ensure that the agent filter element precedes all the other <filter> elements. Similarly, the filter mapping element should be before all the other <filter-mapping> elements. In practice, the agent filter should first intercept the request to properly enforce policies on the whole application.

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

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.

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

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:

Deployment container
Access Manager
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