This chapter covers installation of the policy agent for IBM WebSphere.
Make sure OpenAM is installed and running, and that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in the Administration Guide section on Creating Agent Profiles. To protect resources with the agent also create at least one policy as described in the section on Configuring Policies. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources, in order to test your policy agent after installation.
You must install WebSphere before you install the policy agent, and you must stop the server during installation.
You must install a Java 6 runtime environment, and set the
JAVA_HOME environment variable.
$ echo $JAVA_HOME /path/to/java1.6 $ which java /usr/bin/java
If you are using IBM Java, see Procedure 14.1, “To Install With IBM Java”.
>Go to Obtaining OpenAM Software to determine which version of the agent to download and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page.
Unzip the file in the directory where you plan to install the J2EE policy agent. The agent you install stores its configuration and logs under this directory.
When you unzip the policy agent, you find the following directories
The installation and configuration program, agentadmin.
Configuration templates used by the agentadmin command during installation
Agent web application that handles notifications and Cross Domain SSO
Location for log files written during installation
Shared libraries used by the J2EE policy agent
Property files used by the installation program
Sample application that demonstrates key features of the policy agent. Wait until you have installed the agent to deploy this.
The WebSphere policy agent runs with IBM Java. In order to install the policy agent using IBM Java on platforms other than AIX, you must first change the agentadmin script to use IBMJCE.
Open the file,
bin/agentadmin.bat on Windows), for editing.
Edit the line specifying
AGENT_OPTS on platforms
other than AIX.
AGENT_OPTS="-DamKeyGenDescriptor.provider=IBMJCE \ -DamCryptoDescriptor.provider=IBMJCE -DamRandomGenProvider=IBMJCE"
Edit the last line to include the IBMJCE settings before the classpath is set.
$JAVA_VM \ -DamCryptoDescriptor.provider=IBMJCE -DamKeyGenDescriptor.provider=IBMJCE \ -classpath "$AGENT_CLASSPATH" $AGENT_OPTS \ com.sun.identity.install.tools.launch.AdminToolLauncher $*
Save your work.
You can now install the WebSphere policy agent with IBM Java as described in Section 14.2, “Installing the WebSphere Policy Agent”.
Complete the following procedures to install the policy agent.
Regardless of whether you store configurations centrally in OpenAM or locally with your agents, the agent requires a profile so that it can connect to and communicate with OpenAM.
In the OpenAM console, browse to Access Control >
Realm Name > Agents > J2EE,
and then click the New... button in the Agent table.
Complete the web form using the following hints.
The name for the agent profile used when you install the agent
Password the agent uses to authenticate to OpenAM
Centralized configurations are stored in the OpenAM configuration store. You can manage the centralized configuration through the OpenAM console. Local configurations are stored in a file alongside the agent.
The full URL to an OpenAM instance, or if OpenAM is deployed in a site configuration (behind a load balancer) then the site URL
In centralized configuration mode, the Server URL is used to populate the agent profile for services such as Login, Logout, Naming, and Cross Domain SSO.
The URL to the J2EE agent application, such as
In centralized configuration mode, the Agent URL is used to populate the Agent Profile for services such as notifications.
Create a text file containing only the password.
$ echo password > /tmp/pwd.txt
Protect the password file you create as appropriate for your operating system.
$ chmod 400 /tmp/pwd.txt
Shut down the WebSphere server where you plan to install the agent.
Make sure OpenAM is running.
Run agentadmin --install to install the agent.
$ /path/to/j2ee_agents/websphere_v61_agent/bin/agentadmin --install ... ----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- Instance Config Directory : /path/to/WebSphere/AppServer/profiles/AppSrv01/config/cells/wwwNode01Cell/ nodes/wwwNode01/servers/server1 Instance Server name : server1 WebSphere Install Root Directory : /path/to/WebSphere/AppServer OpenAM server URL : http://openam.example.com:8080/openam Agent URL : http://www.example.com:9080/agentapp Agent Profile name : WebSphere Agent Agent Profile Password file name : /tmp/pwd.txt ... SUMMARY OF AGENT INSTALLATION ----------------------------- Agent instance name: Agent_001 Agent Bootstrap file location: /path/to/j2ee_agents/websphere_v61_agent/Agent_001/config/ OpenSSOAgentBootstrap.properties Agent Configuration file location /path/to/j2ee_agents/websphere_v61_agent/Agent_001/config/ OpenSSOAgentConfiguration.properties Agent Audit directory location: /path/to/j2ee_agents/websphere_v61_agent/Agent_001/logs/audit Agent Debug directory location: /path/to/j2ee_agents/websphere_v61_agent/Agent_001/logs/debug Install log file location: /path/to/j2ee_agents/websphere_v61_agent/installer-logs/audit/install.log ...
Upon successful completion, the installer has updated the WebSphere configuration, copied the agent libraries to WebSphere's external library directory, and also set up configuration and log directories for the agent.
If the agent is in a different domain than the server, refer to Administration Guide procedure, Configuring Cross-Domain Single Sign On.
Take note of the configuration files and log locations.
Each agent instance that you install on the system has its own
numbered configuration and logs directory. The first agent's configuration
and logs are thus located under the directory
Used to bootstrap the J2EE policy agent, allowing the agent to connect to OpenAM and download its configuration
Only used if you configured the J2EE policy agent to use local configuration
Operational audit log directory, only used if remote logging to OpenAM is disabled
Debug directory where the debug file resides. Useful in troubleshooting policy agent issues.
If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server.
Restart the WebSphere server.
agent application in WebSphere.
For each web application to protect, add the following filter
to the application's
following the opening <web-app> tag. The file for the sample
application delivered with the agent is
<filter> <filter-name>Agent</filter-name> <display-name>Agent</display-name> <description>OpenAM Policy Agent Filter</description> <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>
You might also have to update additional configuration files. See
the sample application located under
If you have a policy configured, you can test your policy agent.
For example, try to browse to a resource that your policy agent protects.
You should be redirected to OpenAM to authenticate, for example as user
you authenticate, OpenAM then redirects you back to the resource you tried
When performing a scripted, silent installation, use
agentadmin --install --saveResponse
to create a response file for scripted installation. Then install silently
using agentadmin --install --useResponse
Shut down the WebSphere server before you uninstall the policy agent.
To remove the J2EE policy agent, use agentadmin --uninstall. You must provide the WebSphere configuration directory location.
Uninstall does not remove the agent instance directory, but you can do so manually after removing the agent configuration from WebSphere.
When using WebSphere Application Server Network Deployment, you must install policy agents on the Deployment Manager, on each Node Agent, and on each Application Server. Installation requires that you stop and then restart the Deployment Manager, each Node Agent, and each Application Server in the Network Deployment.
Before installation, synchronize each server configuration with the
profile saved by the Deployment Manager using the syncNode
command. After agent installation, copy the server configuration for each
node, stored in
server.xml, to the corresponding
Deployment Manager profile. After you have synchronized the configurations,
you must restart the Deployment Manager for the Network Deployment.