<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-websphere'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>Installing the IBM WebSphere Policy Agent</title>

<indexterm><primary>IBM WebSphere Application Server</primary></indexterm>

<para>This chapter covers installation of the policy agent for IBM

WebSphere.</para>

<section xml:id="before-websphere-agent-install">

<title>Before You Install</title>

<para>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 <citetitle>Administration Guide</citetitle>

section on <link xlink:href="admin-guide#create-agent-profiles"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Creating Agent

Profiles</citetitle></link>. To protect resources with the agent also create

at least one policy as described in the section on <link

xlink:href="admin-guide#configure-authz-policy"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

Policies</citetitle></link>. 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.</para>

<para>You must install WebSphere before you install the policy agent, and you

must stop the server during installation.</para>

<para>You must install a Java 6 runtime environment, and set the

<literal>JAVA_HOME</literal> environment variable.</para>

<screen>$ echo $JAVA_HOME

/path/to/java1.6

$ which java

/usr/bin/java</screen>

<para>If you are using IBM Java, see <xref linkend="install-with-ibm-jvm" />.</para>

<para>>Go to <link xlink:href="install-guide#download-openam-software"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Obtaining OpenAM Software</citetitle></link>

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.</para>

<para>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.</para>

<variablelist>

<para>When you unzip the policy agent, you find the following directories

under the <filename>j2ee_agents/websphere_v61_agent</filename> directory.</para>

<para>Despite the directory name, the policy agent supports

<?eval ${agentWebSphereSupport}?>.</para>

<varlistentry>

<term><filename>bin</filename></term>

<listitem>

<para>The installation and configuration program,

<command>agentadmin</command>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>config</filename></term>

<listitem>

<para>Configuration templates used by the <command>agentadmin</command>

command during installation</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>data</filename></term>

<listitem>

<para>Not used</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>etc</filename></term>

<listitem>

<para>Agent web application that handles notifications and Cross

Domain SSO</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>installer-logs</filename></term>

<listitem>

<para>Location for log files written during installation</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>lib</filename></term>

<listitem>

<para>Shared libraries used by the J2EE policy agent</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>locale</filename></term>

<listitem>

<para>Property files used by the installation program</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>sampleapp</filename></term>

<listitem>

<para>Sample application that demonstrates key features of the policy

agent. Wait until you have installed the agent to deploy this.</para>

</listitem>

</varlistentry>

</variablelist>

<procedure xml:id="install-with-ibm-jvm">

<title>To Install With IBM Java</title>

<para>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 <command>agentadmin</command> script to use IBMJCE.</para>

<step>

<para>Open the file, <filename>bin/agentadmin</filename>

(<filename>bin/agentadmin.bat</filename> on Windows), for editing.</para>

</step>

<step>

<para>Edit the line specifying <literal>AGENT_OPTS</literal> on platforms

other than AIX.</para>

<literallayout class="monospaced"

>AGENT_OPTS="-DamKeyGenDescriptor.provider=IBMJCE \

-DamCryptoDescriptor.provider=IBMJCE -DamRandomGenProvider=IBMJCE"</literallayout>

</step>

<step>

<para>Edit the last line to include the IBMJCE settings before the

classpath is set.</para>

<literallayout class="monospaced"

>$JAVA_VM \

-DamCryptoDescriptor.provider=IBMJCE -DamKeyGenDescriptor.provider=IBMJCE \

-classpath "$AGENT_CLASSPATH" $AGENT_OPTS \

com.sun.identity.install.tools.launch.AdminToolLauncher $*</literallayout>

</step>

<step>

<para>Save your work.</para>

<para>You can now install the WebSphere policy agent with IBM Java as

described in <xref linkend="install-websphere-agent" />.</para>

</step>

</procedure>

</section>

<section xml:id="install-websphere-agent">

<title>Installing the WebSphere Policy Agent</title>

<para>Complete the following procedures to install the policy agent.</para>

<procedure xml:id="create-websphere-agent-profile">

<title>To Create the WebSphere Agent Profile</title>

<para>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.</para>

<step>

<para>In the OpenAM console, browse to Access Control &gt;

<replaceable>Realm Name</replaceable> &gt; Agents &gt; J2EE,

and then click the New... button in the Agent table.</para>

</step>

<step>

<para>Complete the web form using the following hints.</para>

<variablelist>

<varlistentry>

<term>Name</term>

<listitem>

<para>The name for the agent profile used when you install the

agent</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password</term>

<listitem>

<para>Password the agent uses to authenticate to OpenAM</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Configuration</term>

<listitem>

<para>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.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Server URL</term>

<listitem>

<para>The full URL to an OpenAM instance, or if OpenAM is deployed in

a site configuration (behind a load balancer) then the site URL</para>

<para>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.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Agent URL</term>

<listitem>

<para>The URL to the J2EE agent application, such as

<literal>http://www.example.com:8080/agentapp</literal></para>

<para>In centralized configuration mode, the Agent URL is used to

populate the Agent Profile for services such as notifications.</para>

</listitem>

</varlistentry>

</variablelist>

</step>

</procedure>

<procedure xml:id="create-websphere-agent-pwdfile">

<title>To Create the Password File</title>

<step>

<para>Create a text file containing only the password.</para>

<screen>$ echo password > /tmp/pwd.txt</screen>

</step>

<step>

<para>Protect the password file you create as appropriate for your

operating system.</para>

<screen>$ chmod 400 /tmp/pwd.txt</screen>

</step>

</procedure>

<procedure xml:id="install-agent-into-websphere">

<title>To Install the Policy Agent into WebSphere</title>

<step>

<para>Shut down the WebSphere server where you plan to install the

agent.</para>

</step>

<step>

<para>Make sure OpenAM is running.</para>

</step>

<step>

<para>Run <command>agentadmin --install</command> to install the agent.</para>

<screen>$ /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/

<?eval ${agentsBootstrapFile}?>

Agent Configuration file location

/path/to/j2ee_agents/websphere_v61_agent/Agent_001/config/

<?eval ${agentsConfigurationFile}?>

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

...</screen>

<para>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.</para>

<note>

<para>If the agent is in a different domain than the server, refer to <citetitle>Administration Guide</citetitle> procedure, <link

xlink:href="admin-guide#chap-cdsso"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring Cross-Domain

Single Sign On</citetitle></link>.</para>

</note>

</step>

<step>

<para>Take note of the configuration files and log locations.</para>

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

<filename>j2ee_agents/websphere_v61_agent/Agent_001/</filename>.</para>

<variablelist>

<varlistentry>

<term><filename>config/<?eval ${agentsBootstrapFile}?></filename></term>

<listitem>

<para>Used to bootstrap the J2EE policy agent, allowing the agent to

connect to OpenAM and download its configuration</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>config/<?eval ${agentsConfigurationFile}?></filename></term>

<listitem>

<para>Only used if you configured the J2EE policy agent to use local

configuration</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>logs/audit/</filename></term>

<listitem>

<para>Operational audit log directory, only used if remote logging

to OpenAM is disabled</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>logs/debug/</filename></term>

<listitem>

<para>Debug directory where the debug file resides. Useful in

troubleshooting policy agent issues.</para>

</listitem>

</varlistentry>

</variablelist>

</step>

<step>

<para>If your policy agent configuration is not in the top-level realm (/),

then you must edit config/<?eval ${agentsBootstrapFile}?> 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. </para>

</step>

<step>

<para>Restart the WebSphere server.</para>

</step>

</procedure>

<procedure xml:id="protect-websphere-apps-after-agent-installation">

<title>To Protect Applications After Agent Installation</title>

<step performance="optional">

<para>Deploy the

<filename>/path/to/j2ee_agents/websphere_v61_agent/etc/agentapp.war</filename>

agent application in WebSphere.</para>

</step>

<step>

<para>For each web application to protect, add the following filter

to the application's <filename>web.xml</filename> configuration,

following the opening &lt;web-app&gt; tag. The file for the sample

application delivered with the agent is

<filename>/path/to/j2ee_agents/websphere_v61_agent/sampleapp/etc/web.xml</filename>.</para>

<programlisting language="xml"> &lt;filter&gt;

&lt;filter-name&gt;Agent&lt;/filter-name&gt;

&lt;display-name&gt;Agent&lt;/display-name&gt;

&lt;description&gt;OpenAM Policy Agent Filter&lt;/description&gt;

&lt;filter-class&gt;com.sun.identity.agents.filter.AmAgentFilter&lt;/filter-class&gt;

&lt;/filter&gt;

&lt;filter-mapping&gt;

&lt;filter-name&gt;Agent&lt;/filter-name&gt;

&lt;url-pattern&gt;/*&lt;/url-pattern&gt;

&lt;dispatcher&gt;REQUEST&lt;/dispatcher&gt;

&lt;dispatcher&gt;INCLUDE&lt;/dispatcher&gt;

&lt;dispatcher&gt;FORWARD&lt;/dispatcher&gt;

&lt;dispatcher&gt;ERROR&lt;/dispatcher&gt;

&lt;/filter-mapping&gt;</programlisting>

<para>You might also have to update additional configuration files. See

the sample application located under

<filename>/path/to/j2ee_agents/websphere_v61_agent/sampleapp</filename>

for examples.</para>

</step>

<step performance="optional">

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

<literal>demo</literal>, password <literal>changeit</literal>. After

you authenticate, OpenAM then redirects you back to the resource you tried

to access.</para>

</step>

</procedure>

</section>

<section xml:id="silent-websphere-agent-installation">

<title>Silent WebSphere Policy Agent Installation</title>

<para>When performing a scripted, silent installation, use

<command>agentadmin --install --saveResponse

<replaceable>response-file</replaceable></command>

to create a response file for scripted installation. Then install silently

using <command>agentadmin --install --useResponse

<replaceable>response-file</replaceable></command>.</para>

</section>

<section xml:id="uninstall-websphere-agent">

<title>Removing WebSphere Policy Agent Software</title>

<para>Shut down the WebSphere server before you uninstall the

policy agent.</para>

<para>To remove the J2EE policy agent, use <command>agentadmin

--uninstall</command>. You must provide the WebSphere configuration directory

location.</para>

<para>Uninstall does not remove the agent instance directory, but you can

do so manually after removing the agent configuration from WebSphere.</para>

</section>

<section xml:id="websphere-network-deployment">

<title>Notes About WebSphere Network Deployment</title>

<para>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.</para>

<para>Before installation, synchronize each server configuration with the

profile saved by the Deployment Manager using the <command>syncNode</command>

command. After agent installation, copy the server configuration for each

node, stored in <filename>server.xml</filename>, to the corresponding

Deployment Manager profile. After you have synchronized the configurations,

you must restart the Deployment Manager for the Network Deployment.</para>

</section>

</chapter>