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

<chapter xml:id='chap-jboss'

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 JBoss Application Server Policy Agent</title>

<indexterm><primary>JBoss Application Server</primary></indexterm>

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

Application Server.</para>

<section xml:id="before-jboss-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 JBoss 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>>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/jboss_v42_agent</filename> directory.</para>

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

<?eval ${agentJBossSupport}?>.</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 configuration templates used during

installation</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-jboss-agent">

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

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

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

<title>To Create the JBoss 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-jboss-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-jboss">

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

<step>

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

...

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

SUMMARY OF YOUR RESPONSES

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

JBoss Server Config Directory : /path/to/jboss/server/default/conf

JBoss Server Home Directory : /path/to/jboss

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

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

Agent Profile name : JBoss Agent

Agent Profile Password file name : /tmp/pwd.txt

Agent permissions gets added to java permissions policy file : false

...

SUMMARY OF AGENT INSTALLATION

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

Agent instance name: Agent_001

Agent Bootstrap file location:

/path/to/j2ee_agents/jboss_v42_agent/Agent_001/config/

<?eval ${agentsBootstrapFile}?>

Agent Configuration file location

/path/to/j2ee_agents/jboss_v42_agent/Agent_001/config/

<?eval ${agentsConfigurationFile}?>

Agent Audit directory location:

/path/to/j2ee_agents/jboss_v42_agent/Agent_001/logs/audit

Agent Debug directory location:

/path/to/j2ee_agents/jboss_v42_agent/Agent_001/logs/debug

Install log file location:

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

...</screen>

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

configuration, created a

<filename>JBOSS_HOME/bin/setAgentClasspathdefault.sh</filename> script,

added the agent web application under

<filename>JBOSS_HOME/server/default/deploy/</filename>, 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/jboss_v42_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>To protect a web application, you must 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/jboss_v42_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 must also add the following security domain specification to the

application's <filename>jboss.xml</filename> and

<filename>jboss-web.xml</filename> configuration files.</para>

<programlisting language="xml">&lt;security-domain&gt;java:/jaas/AMRealm&lt;/security-domain&gt;</programlisting>

</step>

</procedure>

<procedure xml:id="run-jboss-after-agent-installation">

<title>To Run JBoss After Agent Installation</title>

<step>

<para>Render the script to set the agent classpath executable.</para>

<screen>$ chmod +x $JBOSS_HOME/bin/setAgentClasspathdefault.sh</screen>

</step>

<step>

<para>Open the <filename>JBOSS_HOME/bin/run.sh</filename> script for

editing, and locate the following code block.</para>

<programlisting language="shell">if [ "x$JBOSS_CLASSPATH" = "x" ]; then

JBOSS_CLASSPATH="$JBOSS_BOOT_CLASSPATH"

else

JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$JBOSS_BOOT_CLASSPATH"

fi

if [ "x$JAVAC_JAR_FILE" != "x" ]; then

JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$JAVAC_JAR_FILE"

fi</programlisting>

</step>

<step>

<para>Edit the <filename>JBOSS_HOME/bin/run.sh</filename> script

to set the classpath needed for the agent, by adding these lines after

the code block you located in the previous step.</para>

<programlisting language="shell">if [ -r "$JBOSS_HOME/bin/setAgentClasspathdefault.sh" ]; then

. $JBOSS_HOME/bin/setAgentClasspathdefault.sh

fi</programlisting>

</step>

<step>

<para>Start the JBoss server where you installed the agent.</para>

<screen>$ cd $JBOSS_HOME ; /bin/run.sh -b 0.0.0.0

...

16:30:31,172 INFO [ServerImpl] JBoss ... Started in 1m:44s:759ms</screen>

</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-jboss-agent-installation">

<title>Silent JBoss 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-jboss-agent">

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

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

policy agent.</para>

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

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

</section>

</chapter>