Skip to end of metadata
Go to start of metadata

Start here: https://backstage.forgerock.com/#!/docs/openam-jee-policy-agents/3.5/jee-users-guide#chap-apache-tomcat

 

There are, unfortunately, quite a lot of individual steps to installing JASAP on Tomcat, all of which must be followed before an install will be successful.

Create the Agent User

The first step is to create the Agent User in the XUI.  If you are planning to reuse an existing agent, forget it - delete it and start again.  There are too many pitfalls in going from, say, port 8020 to port 8030.

Start OpenAM

You must start the OpenAM instance and have it running in order to install.

Stop any running Agent

If you're reinstalling an Agent, you will need to kill any Tomcat that is running the "old" Agent.

Use a response file

If you're going to be installing the Agent a lot, you may want to create a response file.  For me, this looks like:

# Agent User Response File
CONFIG_DIR= /opt/tomcats/openam3/conf
AM_SERVER_URL= http://openam.example.com:8010/openam
CATALINA_HOME= /opt/tomcats/openam3
INSTALL_GLOBAL_WEB_XML= false
AGENT_URL= http://agent.example.com:8030/agentapp
AGENT_PROFILE_NAME= J2EE-TOMCAT
AGENT_PASSWORD_FILE= /Users/tonybamford/IMPORTANT/tomcat-jee-agent-password

Uninstall the old Agent

If you have an old Agent which you're going to install over, it is a good idea to uninstall the old one first.  The command to do this is:

<PATH-TO-ALREADY-INSTALLED-WEB-AGENT>/bin/agentadmin --uninstall --useResponse <YOUR-RESPONSE-FILE> --acceptLicense

Find somewhere permanent and unpack the installation zip there

You will find your installation zip file in the source directory where you built the Agent.  It will be called something like jee-agents-distribution/jee-agents-distribution-tomcat-v6/target/tomcat_v6_agent_x.x.x-SNAPSHOT.zip

You will need a permanent directory somewhere in which to install the Agent (i.e. to unzip this file and leave the results around permanently), and I'm not talking about anywhere under your Tomcat directory.  Do not use anything under /tmp or things will break - probably sooner rather than later.

When you have established where this directory will be, cd there and unzip the installation zip file.

Run the installer

Once unpacked, you will find a bin directory containing an agentadmin script.  Yes, it's a shell script.  There is a batch file available for DOS users.  Invoke this as:

agentadmin --install --useResponse <YOUR-RESPONSE-FILE> --acceptLicense

If you don't have a response file, just leave out this part and suffer being asked lots of annoying questions to which the answer is not readily apparent.

Optionally turn on debugging within the Agent

The file OpenSSOAgentBootstrap.properties will be nested a couple of directories below.  Find this file and change the property com.iplanet.services.debug.level to have an empty value (when the value is empty, debugging is set to "message" which is the highest debugging level available).

Protect every webapp you want to access

If you want, for example, the Agent to protect the Tomcat "examples" webapp, you will need to alter its web.xml file (in <YOUR-PATH-TO-TOMCAT>/webapps/examples/WEB-INF/web.xml) and add:

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

I usually put this at the top, right under <display-name>

Start up Tomcat as normal and rejoice in the protected application.

  • No labels