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

<chapter xml:id='chap-weblogic'

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 Oracle WebLogic Policy Agent</title>

<indexterm><primary>Oracle WebLogic Server</primary></indexterm>

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

WebLogic.</para>

<section xml:id="before-weblogic-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 WebLogic before you install the policy agent, and you

must stop the server during installation.</para>

<para>You must install a supported version of the Java runtime environment.

Please review the <link xlink:show="new"

xlink:href="http://openam.forgerock.org/openam-documentation/openam-doc-source/doc/release-notes/#java-requirements">

<citetitle>OpenAM Release Notes</citetitle></link> for the currently supported version

of Java, and set the <literal>JAVA_HOME</literal> environment

variable accordingly.</para>

<screen>$ echo $JAVA_HOME

/path/to/java

$ which java

/usr/bin/java</screen>

<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/weblogic_v10_agent</filename> directory.</para>

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

<?eval ${agentWebLogicSupport}?>.</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 and startup configuration</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>

</section>

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

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

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

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

<title>To Create the WebLogic 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-weblogic-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-weblogic">

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

<step>

<para>Shut down the WebLogic 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/weblogic_v10_agent/bin/agentadmin --install

...

-----------------------------------------------

SUMMARY OF YOUR RESPONSES

-----------------------------------------------

Startup script location :

/path/to/domain/mydomain/bin/startWebLogic.sh

WebLogic Server instance name : AdminServer

WebLogic home directory : /path/to/wlserver

OpenAM server URL : http://openam.example.com:8080/openam

Agent URL : http://www.example.com:7001/agentapp

Agent Profile name : WebLogic 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/weblogic_v10_agent/Agent_001/config/

<?eval ${agentsBootstrapFile}?>

Agent Configuration file location

/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/config/

<?eval ${agentsConfigurationFile}?>

Agent Audit directory location:

/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/logs/audit

Agent Debug directory location:

/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/logs/debug

Install log file location:

/path/to/j2ee_agents/weblogic_v10_agent/installer-logs/audit/install.log

...</screen>

<para>Upon successful completion, the installer has updated the WebLogic

configuration, copied the agent libraries to WebLogic's 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/weblogic_v10_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>The agent requires sourcing before it will work properly. There are two

ways to source.</para>

<stepalternatives>

<step>

<para>Manually source the file containing the policy agent environment settings for

WebLogic before starting the application server. </para>

<screen>. /path/to/setAgentEnv_AdminServer.sh</screen>

</step>

<step>

<para>Or edit the <filename>startWebLogic.sh</filename> script to set the sourcing

needed for the agent, by adding these lines after the code block shown. Add the

setAgentEnv_AdminServer.sh line to the following location in the file. The drawback

to this approach is that it could be overwritten, as noted in the file.</para>

<screen>$ vi /path/to/startWebLogic.sh

# Any changes to this script may be lost when adding extensions to this configuration.

DOMAIN_HOME="/opt/Oracle/Middleware/user_projects/domains/base_domain"

. /path/to/setAgentEnv_AdminServer.sh

${DOMAIN_HOME}/bin/startWebLogic.sh $*</screen>

</step>

</stepalternatives>

<note>

<para>If the sourcing is not properly set, the following message appears.</para>

<screen>&lt;Error&gt; &lt;HTTP&gt; &lt;cent.example.com&gt;

&lt;AdminServer&gt; &lt;[STANDBY] ExecuteThread: '5' for queue: 'weblogic.kernel.Default

(self-tuning)'&gt; &lt;&lt;WLS Kernel&gt;&gt; &lt;&gt;&lt;&gt; &lt;&gt; &lt;1360800613441&gt;

&lt;BEA-101165&gt; &lt;Could not load user defined filter in web.xml:

ServletContext@1761850405[app:agentapp module:agentapp.war path:null

spec-version:null] com.sun.identity.agents.filter.AmAgentFilter.

java.lang.ClassNotFoundException: com.sun.identity.agents.filter.AmAgentFilter</screen>

</note>

</step>

<step>

<para>Start the WebLogic server.</para>

</step>

<!-- Fix for OpenAM-945: Document WebLogic install process change -->

<step>

<para>Configure shutdown classes for the environment.</para>

<substeps>

<step>

<para>In WebLogic console, browse to Environment &gt; Startup &amp;

Shutdown Classes.</para>

</step>

<step>

<para>Click Lock &amp; Edit.</para>

</step>

<step>

<para>Click New.</para>

</step>

<step>

<para>Select the Shutdown Class option, and then click Next.</para>

</step>

<step>

<para>Provide the Name <literal>Agent</literal>, and the Class Name

<literal>org.forgerock.agents.weblogic.v10.lifecycle.ShutdownListener</literal>.</para>

</step>

<step>

<para>Select the appropriate targets to call the shutdown class once per

Java Virtual Machine, and then click Finish.</para>

</step>

<step>

<para>Click Activate Changes.</para>

</step>

</substeps>

</step>

</procedure>

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

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

<step performance="optional">

<para>Deploy the

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

agent application in WebLogic.</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/weblogic_v10_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/weblogic_v10_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-weblogic-agent-installation">

<title>Silent WebLogic 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="post-weblogic-agent-installation">

<title>Post Installation of WebLogic Policy Agent</title>

<para>After installing WebLogic, some configuration is required before

the policy agent will work.</para>

<procedure xml:id="configure-weblogic-agent">

<title>To Configure the WebLogic Policy Agent</title>

<para>WebLogic is unique in that it requires additional configuration

after the installation is complete.</para>

<step>

<para>Go to the WebLogic Server Administratotion Console and login.</para>

</step>

<step>

<para>Click <literal>Security realms</literal>.</para>

</step>

<step>

<para>Click the name of the realm to use for OpenAM.</para>

</step>

<step>

<para>Click <literal>Providers</literal> > <literal>Authentication</literal>.</para>

</step>

<step>

<para>Click <literal>Lock &amp; Edit</literal> > <literal>New</literal>.</para>

</step>

<step>

<para>Enter the desired type in <literal>Type as AgentAuthenticator</literal>,

provide a name, and click <literal>OK</literal>.</para>

</step>

<step>

<para>Click on the name of the agent authenticator you just created.</para>

</step>

<step>

<para>Use <literal>OPTIONAL</literal> for the control flag and save.</para>

</step>

<step>

<para>Click on <literal>Providers</literal> to display the Authentication

Providers Table.</para>

</step>

<step>

<para>Click on <literal>Default Authenticator</literal>, use <literal>OPTIONAL</literal>

for the control flag, and save.</para>

</step>

<step>

<para>Activate the changes once the default authenticator is done saving.</para>

<para>You will need to restart the WebLogic Server to implement the changes.</para>

</step>

</procedure>

</section>

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

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

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

policy agent.</para>

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

--uninstall</command>. You must provide the WebLogic 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 WebLogic.</para>

</section>

</chapter>