Install Java Agent
Install Tomcat Java Agent
Before you install, make sure that all Tomcat scripts are present in the
$CATALINA_HOME/bin
directory. The Tomcat Windows executable installer
does not include the scripts. If the scripts are not present in your
installation, copy the contents of the bin
directory from a .zip
download of Tomcat of the same version as the one you installed.
Install Tomcat Java Agent interactively
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Shut down the Tomcat server where you plan to install the agent.
-
Make sure AM is running.
-
Run
agentadmin --install
to install the agent:$ /path/to/java_agents/tomcat_agent/bin/agentadmin --install
You are prompted to read and accept the software license agreement for the agent installation.
-
When prompted, enter information for your deployment.
To cancel the installation at any time, press CTRL+C
.-
Enter the complete path to the Tomcat configuration folder:
... [ ? : Help, ! : Exit ] Enter the Tomcat Server Config Directory Path [/opt/apache-tomcat/conf]: /path/to/apache-tomcat/conf
-
Enter the AM URL:
... [ ? : Help, < : Back, ! : Exit ] AM server URL: https://openam.example.com:8443/openam
To load balance connections between the agent and an AM site, enter the URL of the load balancer in front of the AM site.
If a reverse proxy is configured between AM and the agent, enter the proxy URL. For more information, see Configure an Apache HTTP Server as a reverse proxy.
-
Enter the
$CATALINA_HOME
environment variable, specifying the path to the root of the Tomcat server:... [ ? : Help, < : Back, ! : Exit ] Enter the $CATALINA_HOME environment variable: /path/to/apache-tomcat
-
Enter the agent URL:
... [ ? : Help, < : Back, ! : Exit ] Agent URL: \http://agent.example.com:80/app
-
Enter the name of the agent profile created in AM:
... [ ? : Help, < : Back, ! : Exit ] Enter the Agent Profile name: java-agent
-
Enter the AM realm containing the agent profile. Realms are case-sensitive.
... [ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ] Enter the Agent Profile realm [/]:
-
Enter the path to the password file you created during pre-installation:
... [ ? : Help, < : Back, ! : Exit ] Enter the path to the password file: /secure-directory/pwd.txt
-
Enter the path to a file that contains the agent pre-authentication cookie signing value
... [ ? : Help, < : Back, ! : Exit ] Enter the path to the signing file:
Provide a path to a file containing a randomly generated key that is at least 64 characters in length, but preferably about 80 characters.
To disable cookie signing, press return without providing a value.
-
-
Review a summary, and select how to continue:
... Verify your settings above and decide from the choices below. 1. Continue with Installation 2. Back to the last interaction 3. Start Over 4. Exit Please make your selection [1]: 1 ...
After successful installation, the installer adds the agent configuration to the Tomcat configuration, and sets up configuration and log directories for the agent.
-
Test the installation by browsing to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the requested resource.
Install Tomcat Java Agent silently
Use the agentadmin --useResponse
command for silent installation.
For information about the option, see agentadmin command.
The following example uses a response file containing the same configuration as in Install Tomcat Java Agent interactively.
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Shut down the Tomcat server where you plan to install the agent.
-
Make sure AM is running.
-
Create a response file with the following content, at
/path/to/response-file
:# Response File CONFIG_DIR= /path/to/apache-tomcat/conf AM_SERVER_URL= https://am.example.com:8443/am CATALINA_HOME= /path/to/apache-tomcat AGENT_URL= \http://agent.example.com:80/app AGENT_PROFILE_NAME= java-agent AGENT_PROFILE_REALM= / AGENT_PASSWORD_FILE= /secure-directory/pwd.txt AGENT_SIGNING_FILE= /secure-directory/signing-key.txt
-
Run the
agentadmin
command with the--useResponse
option:$ agentadmin --install --useResponse /path/to/response-file
Install in a subrealm
Other installation examples install the agent in the top-level realm. To install the agent in a subrealm during interactive or silent installation, use the subrealm during the installation or in the response file. For example, instead of:
AGENT_PROFILE_REALM = /
specify:
AGENT_PROFILE_REALM = /myrealm
Even though the agent is installed in a subrealm, the default login redirect requires users to log into the top-level realm. For information about how to change the login, see Use the request domain to redirect login to a different realm.
Install JBoss Java Agent
The examples in this section assume that you are using JBoss, but the procedures are the same for WildFly. Agent binaries for JBoss and WildFly are the same.
Install JBoss Java Agent interactively
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Shut down the JBoss server where you plan to install the agent.
-
Make sure AM is running.
-
Run
agentadmin --install
to install the agent:$ /path/to/java_agents/jboss_agent/bin/agentadmin --install
You are prompted to read and accept the software license agreement for the agent installation.
-
Enter the absolute path to the JBoss installation directory:
... [ ? : Help, ! : Exit ] Enter the path to the JBoss installation: /path/to/jboss
-
Enter the name of the deployment mode for the JBoss installation:
-
standalone
: Manage a single JBoss instanceIn standalone mode, the agent installer uses an auto-deployment feature provided by the JBoss deployment scanner so that you do not have to deploy the
agentapp.war
manually. -
domain
: Manage multiple server instances from a single control point.In this mode, at the end of the procedure, you must manually deploy the
java_agents/jboss_agent/etc/agentapp.war
file to JBoss.
-
-
Enter the name of the profile to use in
standalone
ordomain
mode:-
standalone
: Default. -
full
: Supports Java EE 6 Full Profile, and subsystems that are not required for high-availability. -
ha
: Enables all default subsystems, and adds the clustering capabilities. -
full-ha
: Enables all default subsystems, including those required for high-availability, and adds clustering capabilities.
-
-
Choose whether to deploy the agent as a global JBoss module.
... [ ? : Help, < : Back, ! : Exit ] Install agent as global module? [true]: true
To include specific modules for a web application, enter
false
, and complete the additional steps at the end of this procedure. -
Enter the AM URL, including the deployment URI:
... [ ? : Help, < : Back, ! : Exit ] AM server URL: https://am.example.com:8443/am
To load balance connections between the agent and an AM site, enter the URL of the load balancer in front of the AM site.
If a reverse proxy is configured between AM and the agent, enter the proxy URL. For more information, see Configure an Apache HTTP Server as a reverse proxy.
-
Enter the agent URL:
... [ ? : Help, < : Back, ! : Exit ] Agent URL: \http://agent.example.com:80/app
-
Enter the agent profile name created in AM as part of the pre-installation procedure:
... [ ? : Help, < : Back, ! : Exit ] Enter the Agent Profile name: JBossAgent
-
Enter the realm in which the specified agent profile exists.
Press ENTER to accept the default value of
/
for the top-level realm. If you specify the(^) : Accept Empty value
option, the top-level realm is used.... [ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ] Enter the Agent Profile realm [/]:
-
Enter the path to the password file you created as part of the pre-installation procedure:
... [ ? : Help, < : Back, ! : Exit ] Enter the path to the password file: /secure-directory/pwd.txt
-
Enter the path to a file that contains the agent pre-authentication cookie signing value
... [ ? : Help, < : Back, ! : Exit ] Enter the path to the signing file:
Provide a path to a file containing a randomly generated key that is at least 64 characters in length, but preferably about 80 characters.
To disable cookie signing, press return without providing a value.
-
Review a summary of your responses and select how to continue:
... Verify your settings above and decide from the choices below. 1. Continue with Installation 2. Back to the last interaction 3. Start Over 4. Exit Please make your selection [1]: 1 ...
After successful completion, the installer updates the JBoss configuration, adds the agent web application under
JBOSS_HOME/server/standalone/deployments
, and sets up configuration and log directories for the agent. -
Follow these steps if you responded
false
to the questionDeploy the policy agent as a global JBoss module
during the installation:-
Add the following line to the web application file
/path/to/protected/app/META-INF/MANIFEST.MF
:Dependencies: org.forgerock.openam.agent
-
Create a file at
/path/to/protected/app/WEB-INF/jboss-deployment-structure.xml
with the following content:<?xml version="1.0"?> <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <deployment> <dependencies> <module name="org.forgerock.openam.agent" > <imports> <include path="META-INF"/> <include path="org"/> </imports> </module> </dependencies> </deployment> </jboss-deployment-structure>
-
-
If you chose
domain
as the deployment mode, manually deploy thejava_agents/jboss_agent/etc/agentapp.war
file to JBoss. -
Test the installation by browsing to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the requested resource.
Install JBoss Java Agent Silently
To install the Java Agent silently, create a response file containing
the installation parameters, and then provide it to the agentadmin
command.
The following is an example response file to install the agent when
JBoss is configured in standalone
mode:
# Agent User Response File
HOME_DIR= /path/to/jboss
INSTANCE_NAME= standalone
GLOBAL_MODULE= true
INSTALL_PROFILE_NAME=
AM_SERVER_URL= https://am.example.com:8443/am
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= JBossAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /secure-directory/pwd.txt
AGENT_SIGNING_FILE= /secure-directory/signing-key.txt
The INSTALL_PROFILE_NAME
variable is used only when the INSTANCE_NAME
is
set to domain
. It specifies the name of the JBoss domain profile.
To load balance connections between the agent and an AM site, set
AM_SERVER_URL
to the URL of the load balancer in front of the AM site.
If a reverse proxy is configured between AM and the agent, set
AM_SERVER_URL
to the proxy URL. For more information, see
Configure an Apache HTTP Server as a reverse proxy.
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Make sure that the response file for the installation is ready, or create a response file, for example:
$ agentadmin --install --saveResponse response-file
-
Shut down the JBoss server where you plan to install the agent.
-
Make sure AM is running.
-
Run the
agentadmin
command with the--useResponse
option:$ agentadmin --install --useResponse /path/to/response-file
-
If you configured the
GLOBAL_MODULE
variable asfalse
in the response file, add the following line to theMETA-INF/MANIFEST.MF
file of the web application:Dependencies: org.forgerock.openam.agent
-
If you configured the
INSTANCE_NAME
variable asdomain
in the response file, manually deploy thejava_agents/jboss_agent/etc/agentapp.war
file to JBoss.
Install in a subrealm
Other installation examples install the agent in the top-level realm. To install the agent in a subrealm during interactive or silent installation, use the subrealm during the installation or in the response file. For example, instead of:
AGENT_PROFILE_REALM = /
specify:
AGENT_PROFILE_REALM = /myrealm
Even though the agent is installed in a subrealm, the default login redirect requires users to log into the top-level realm. For information about how to change the login, see Use the request domain to redirect login to a different realm.
Install Jetty Java Agent
Command-line examples in this chapter show Jetty accessed remotely. If follow
the examples and have issues accessing Jetty remotely, consider changing
filter settings in the deployment descriptor file,
/path/to/jetty/webapps/test/WEB-INF/web.xml
, as shown in the following
example:
<filter>
<filter-name>TestFilter</filter-name>
<filter-class>com.acme.TestFilter</filter-class>
<init-param>
<param-name>remote</param-name>
<param-value>true</param-value> <!-- default: false -->
</init-param>
</filter>
Install Jetty Java Agent interactively
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Shut down the Jetty server where you plan to install the agent.
-
Make sure AM is running.
-
Run
agentadmin --install
to install the agent:$ /path/to/java_agents/jetty_agent/bin/agentadmin --install
You are prompted to read and accept the software license agreement for the agent installation.
-
Enter the absolute path to the root of the Jetty installation:
... [ ? : Help, ! : Exit ] Enter the Jetty home directory [/opt/jetty]: /path/to/jetty/home
This is the equivalent of the
JETTY_HOME
environment variable for Jetty. -
Enter the absolute path to the Jetty configuration directory:
... [ ? : Help, < : Back, ! : Exit ] Enter the absolute path of the Jetty etc directory: /path/to/jetty/etc
-
Enter the absolute path to the Jetty base directory:
... [ ? : Help, < : Back, ! : Exit ] Enter the Jetty base directory [/usr/local/jetty]: /path/to/jetty/base
This is the equivalent of the
JETTY_BASE
environment variable for Jetty.This path may be the same as the one specified as the root of the Jetty installation.
-
Enter the AM URL, including the deployment URI:
... [ ? : Help, < : Back, ! : Exit ] AM server URL: https://am.example.com:8443/am
To load balance connections between the agent and an AM site, enter the URL of the load balancer in front of the AM site.
If a reverse proxy is configured between AM and the agent, enter the proxy URL. For more information, see Configure an Apache HTTP Server as a reverse proxy.
-
Enter the agent URL:
... [ ? : Help, < : Back, ! : Exit ] Agent URL: \http://agent.example.com:80/app
-
Enter the agent profile name created in AM as part of the pre-installation procedure:
... [ ? : Help, < : Back, ! : Exit ] Enter the Agent Profile name: JettyAgent
-
Enter the realm in which the specified agent profile exists.
Press ENTER to accept the default value of
/
for the top-level realm. If you specify the(^) : Accept Empty value
option, the top-level realm is used.... [ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ] Enter the Agent Profile realm [/]:
-
Enter the path to the password file you created as part of the pre-installation procedure:
... [ ? : Help, < : Back, ! : Exit ] Enter the path to the password file: /secure-directory/pwd.txt
-
Enter the path to a file that contains the agent pre-authentication cookie signing value
... [ ? : Help, < : Back, ! : Exit ] Enter the path to the signing file:
Provide a path to a file containing a randomly generated key that is at least 64 characters in length, but preferably about 80 characters.
To disable cookie signing, press return without providing a value.
-
Review a summary of your responses and select how to continue:
… Verify your settings above and decide from the choices below. 1. Continue with Installation 2. Back to the last interaction 3. Start Over 4. Exit Please make your selection [1]: 1 …
After successful completion, the installer updates Jetty’s
start.jar
to reference the agent, sets up the agent web application, and sets up configuration and log directories for the agent. -
Test the installation by browsing to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the requested resource.
Install Jetty Java Agent silently
To install the Java Agent silently, create a response file containing
the installation parameters, and then provide it to the agentadmin
command. The following is an example response file:
# Agent User Response File
CONFIG_DIR= /path/to/jetty/etc
JETTY_HOME= /path/to/jetty/home
JETTY_BASE= /path/to/jetty/base
AM_SERVER_URL= https://am.example.com:8443/am
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= JettyAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /secure-directory/pwd.txt
AGENT_SIGNING_FILE= /secure-directory/signing-key.txt
To load balance connections between the agent and an AM site, set
AM_SERVER_URL
to the URL of the load balancer in front of the AM site.
If a reverse proxy is configured between AM and the agent, set
AM_SERVER_URL
to the proxy URL. For more information, see
Configure an Apache HTTP Server as a reverse proxy.
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Shut down the Jetty server where you plan to install the agent.
-
Make sure that AM is running.
-
Run the
agentadmin
command with the--useResponse
option:$ agentadmin --install --useResponse /path/to/response-file
Install in a subrealm
Other installation examples install the agent in the top-level realm. To install the agent in a subrealm during interactive or silent installation, use the subrealm during the installation or in the response file. For example, instead of:
AGENT_PROFILE_REALM = /
specify:
AGENT_PROFILE_REALM = /myrealm
Even though the agent is installed in a subrealm, the default login redirect requires users to log into the top-level realm. For information about how to change the login, see Use the request domain to redirect login to a different realm.
Install WebLogic Java Agent
Install WebLogic Java Agent interactively
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Shut down the WebLogic server where you plan to install the agent.
-
Make sure AM is running.
-
Run
agentadmin --install
to install the agent:$ /path/to/java_agents/weblogic_agent/bin/agentadmin --install
You are prompted to read and accept the software license agreement for the agent installation.
-
Enter the path to the
startWebLogic.sh
file of the WebLogic domain where you want to install the agent:... [ ? : Help, ! : Exit ] Enter the Startup script location [/usr/local/bea/user_projects/domains/base_domain/startWebLogic.sh]: /path/to/Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh
-
Enter the path to the WebLogic installation directory:
... [ ? : Help, < : Back, ! : Exit ] Enter the WebLogic home directory [/usr/local/bea/wlserver_10.0]: /path/to/weblogic
-
Enter the AM URL, including the deployment URI:
... [ ? : Help, < : Back, ! : Exit ] AM server URL: https://am.example.com:8443/am
To load balance connections between the agent and an AM site, enter the URL of the load balancer in front of the AM site.
If a reverse proxy is configured between AM and the agent, enter the proxy URL. For more information, see Configure an Apache HTTP Server as a reverse proxy.
-
Enter the agent URL:
... [ ? : Help, < : Back, ! : Exit ] Agent URL: \http://agent.example.com:80/app
-
Enter the agent profile name created in AM as part of the pre-installation procedure:
… [ ? : Help, < : Back, ! : Exit ] Enter the Agent Profile name: WebLogicAgent
-
Enter the realm in which the specified agent profile exists.
Press ENTER to accept the default value of
/
for the top-level realm. If you specify the(^) : Accept Empty value
option, the top-level realm is used.... [ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ] Enter the Agent Profile realm [/]:
-
Enter the path to the password file you created as part of the pre-installation procedure:
... [ ? : Help, < : Back, ! : Exit ] Enter the path to the password file: /secure-directory/pwd.txt
-
Enter the path to a file that contains the agent pre-authentication cookie signing value
... [ ? : Help, < : Back, ! : Exit ] Enter the path to the signing file:
Provide a path to a file containing a randomly generated key that is at least 64 characters in length, but preferably about 80 characters.
To disable cookie signing, press return without providing a value.
-
Review a summary of your responses and select how to continue:
$ /path/to/java_agents/weblogic_agent/bin/agentadmin --install ... Verify your settings above and decide from the choices below. 1. Continue with Installation 2. Back to the last interaction 3. Start Over 4. Exit Please make your selection [1]: 1 ...
-
Source the agent in one of the following ways:
-
Manually source the file containing the agent environment settings for WebLogic before starting the container.
$ . /path/to/setAgentEnv_AdminServer.sh
-
Add the
setAgentEnv_AdminServer.sh
line to the shown location [path] in thestartWebLogic.sh
script. Note that the file can be overwritten:$ cat /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 $*
If the sourcing is not set properly, the following message appears:
<Error> <HTTP> <cent.example.com> <AdminServer> <[STANDBY] ExecuteThread: '5' for queue: weblogic.kernel. Default (self-tuning)'> <<WLS Kernel>> <BEA-101165> <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
-
-
Start the WebLogic server.
-
Deploy the
/path/to/java_agents/weblogic_agent/etc/agentapp.war
agent web application in WebLogic. -
Test the installation by browsing to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the requested resource.
Install WebLogic Java Agent silently
To install the Java Agent silently, create a response file containing
the installation parameters, and then provide it to the agentadmin
command. The following is an example response file:
# Agent User Response File
STARTUP_SCRIPT= /path/to/Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh
SERVER_NAME= AdminServer
WEBLOGIC_HOME_DIR= /path/to/weblogic
AM_SERVER_URL= https://am.example.com:8443/am
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= WebLogicAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /secure-directory/pwd.txt
AGENT_SIGNING_FILE= /secure-directory/signing-key.txt
To load balance connections between the agent and an AM site, set
AM_SERVER_URL
to the URL of the load balancer in front of the AM site.
If a reverse proxy is configured between AM and the agent, set
AM_SERVER_URL
to the proxy URL. For more information, see
Configure an Apache HTTP Server as a reverse proxy.
-
Review the information in Before you install, and perform the steps in Preinstallation tasks.
-
Make sure that the response file for the installation is ready, or create a response file, for example:
$ agentadmin --install --saveResponse response-file
-
Shut down the WebLogic server where you plan to install the agent.
-
Make sure AM is running.
-
Run the
agentadmin
command with the--useResponse
option:$ agentadmin --install --useResponse /path/to/response-file
-
Source the agent in one of the following ways:
-
Manually source the file containing the agent environment settings for WebLogic before starting the container.
$ . /path/to/setAgentEnv_AdminServer.sh
-
Add the
setAgentEnv_AdminServer.sh
line to the shown location [path] in thestartWebLogic.sh
script. Note that the file can be overwritten:$ cat /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 $*
If the sourcing is not set properly, the following message appears:
<Error> <HTTP> <cent.example.com> <AdminServer> <[STANDBY] ExecuteThread: '5' for queue: weblogic.kernel. Default (self-tuning)'> <<WLS Kernel>> <BEA-101165> <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
-
-
Start the WebLogic Server.
-
Deploy the
/path/to/java_agents/weblogic_agent/etc/agentapp.war
agent web application in WebLogic.
Install WebLogic Java Agent in multi-server domains
In many WebLogic domains, the administration server provides a central point for controlling and managing the configuration of the managed servers that host protected web applications.
If WebLogic-managed servers run on different hosts, you must create separate agent profiles and perform separate installations for each so that AM can send notifications to the appropriate addresses.
-
If servers are on different hosts, create agent profiles for each server where you plan to install the agent. For more information, see Installing the WebLogic Java Agent.
-
Prepare your protected web applications by adding the agent filter configuration as described in Configure the agent filter for a web application.
-
Use the
agentadmin
command to install the agent either interactively, or silently on each server in the domain:-
For interactive installation, follow the instructions in To install the WebLogic Java Agent.
-
For silent installation, follow the instructions in Installing the WebLogic Java Agent silently.
-
-
On each managed server in the domain, update the classpath to include agent .jar files.
In WebLogic Node Manager console, navigate to Environment > Servers > server > Server Start > Class Path, and then edit the classpath as in the following example, but all on a single line:
/path/to/java_agents/weblogic_agent/lib/agent.jar: /path/to/java_agents/weblogic_agent/lib/openssoclientsdk.jar: ... /path/to/java_agents/weblogic_agent/locale: /path/to/java_agents/weblogic_agent/Agent_001/config: $CLASSPATH
Replace the paths in the example with the actual paths for your domain.
-
Restart the managed servers.