Java Agents 5.10.3

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

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the Tomcat server where you plan to install the agent.

  3. Make sure AM is running.

  4. 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. Use the --acceptLicense option to skip the prompt.

  5. When prompted, enter information for your deployment.

    To cancel the installation at any time, press CTRL+C.

    1. Enter the complete path to the Tomcat configuration folder:

      Enter the complete path to the directory which is used by Tomcat Server to store its configuration Files. This directory uniquely identifies the Tomcat Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Tomcat Server Config Directory Path
[/opt/apache-tomcat/conf]: /path/to/apache-tomcat/conf

    1. Enter the AM URL:

      Enter the URL where the AM server is running. Please include the deployment URI also as shown below:
(http://openam.sample.com:58080/openam)
[ ? : 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.

    2. Enter the $CATALINA_HOME environment variable, specifying the path to the root of the Tomcat server:

      $CATALINA_HOME environment variable is the root of the tomcat
installation.
[ ? : Help, < : Back, ! : Exit ]
Enter the $CATALINA_HOME environment variable: /path/to/apache-tomcat

    3. Enter the agent URL:

      Enter the Agent URL. Please include the deployment URI also as shown below:
(http://agent1.sample.com:1234/agentapp)
[ ? : Help, < : Back, ! : Exit ]
Agent URL: \http://agent.example.com:80/app

    4. Enter the name of the agent profile created in AM:

      Enter the Agent profile name
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: java-agent

    5. Enter the AM realm containing the agent profile. Realms are case-sensitive.

      Enter the Agent profile realm
[ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ]
Enter the Agent Profile realm [/]:

    6. Enter the path to the password file you created during pre-installation:

      Enter the path to a file that contains the password to be used for identifying the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /tmp/pwd.txt

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

      Create arbitrary length keys with the agentadmin --key command.

  6. Review a summary, and select how to continue:

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
...
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.

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

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the Tomcat server where you plan to install the agent.

  3. Make sure AM is running.

  4. 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= /tmp/pwd.txt
AGENT_SIGNING_FILE=/tmp/signing-key.txt

  5. Run the agentadmin command with the --useResponse option:

    $ agentadmin --install --acceptLicense --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

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the JBoss server where you plan to install the agent.

  3. Make sure AM is running.

  4. 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. Use the --acceptLicense option to skip the prompt.

  5. Enter the absolute path to the JBoss installation directory:

    Enter the complete path to the home directory of the JBoss instance.
[ ? : Help, ! : Exit ]
Enter the path to the JBoss installation: /path/to/jboss

  6. Enter the name of the deployment mode for the JBoss installation:

    • standalone: Manage a single JBoss instance

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

  7. Enter the name of the profile to use in standalone or domain 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.

  8. Choose whether to deploy the agent as a global JBoss module.

    Enter true if you'd like to deploy the policy 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.

  9. Enter the AM URL:

    Enter the URL where the AM server is running. Please include the deployment URI also as shown below:
(http://am.sample.com:58080/am)
[ ? : 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.

  10. Enter the agent URL:

    Enter the Agent URL. Please include the deployment URI also as shown below:
(http://agent1.sample.com:1234/agentapp)
[ ? : Help, < : Back, ! : Exit ]
Agent URL: \http://agent.example.com:80/app

  11. Enter the agent profile name created in AM as part of the pre-installation procedure:

    Enter the Agent profile name
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: JBossAgent

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

    Enter the Agent profile realm
[ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ]
Enter the Agent Profile realm [/]:

  13. Enter the path to the password file you created as part of the pre-installation procedure:

    Enter the path to a file that contains the password to be used for identifying the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /tmp/pwd.txt

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

      Create arbitrary length keys with the agentadmin --key command.

  14. Review a summary of your responses and select how to continue:

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
...
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.

  15. Follow these steps if you responded false to the question Deploy the policy agent as a global JBoss module during the installation:

    1. Add the following line to the web application file /path/to/protected/app/META-INF/MANIFEST.MF:

      Dependencies: org.forgerock.openam.agent

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

  16. If you chose domain as the deployment mode, manually deploy the java_agents/jboss_agent/etc/agentapp.war file to JBoss.

  17. 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= /tmp/pwd.txt
AGENT_SIGNING_FILE=/tmp/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.

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Make sure that the response file for the installation is ready, or create a response file, for example:

    $ agentadmin --install --saveResponse response-file

  3. Shut down the JBoss server where you plan to install the agent.

  4. Make sure AM is running.

  5. Run the agentadmin command with the --useResponse option:

    $ agentadmin --install --acceptLicense --useResponse /path/to/response-file

  6. If you configured the GLOBAL_MODULE variable as false in the response file, add the following line to the META-INF/MANIFEST.MF file of the web application:

    Dependencies: org.forgerock.openam.agent

  7. If you configured the INSTANCE_NAME variable as domain in the response file, manually deploy the java_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

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the Jetty server where you plan to install the agent.

  3. Make sure AM is running.

  4. 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. Use the --acceptLicense option to skip the prompt.

  5. Enter the absolute path to the root of the Jetty installation:

    This is the home of the Jetty installation (directory containing start.jar)
[ ? : 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.

  6. Enter the absolute path to the Jetty configuration directory:

    Enter the absolute path of the Jetty etc directory.
[ ? : Help, &lt; : Back, ! : Exit ]
Enter the absolute path of the Jetty etc directory: /path/to/jetty/etc

  7. Enter the absolute path to the Jetty base directory:

    This is the base of the Jetty installation (directory containing the webapps subdirectory)
[ ? : 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.

  8. Enter the AM URL:

    Enter the URL where the AM server is running. Please include the deployment URI also as shown below:
(http://am.sample.com:58080/am)
[ ? : 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.

  9. Enter the agent URL:

    Enter the Agent URL. Please include the deployment URI also as shown below:
(http://agent1.sample.com:1234/agentapp)
[ ? : Help, < : Back, ! : Exit ]
Agent URL: \http://agent.example.com:80/app

  10. Enter the agent profile name created in AM as part of the pre-installation procedure:

    Enter the Agent profile name
[ ? : Help, &lt; : Back, ! : Exit ]
Enter the Agent Profile name: JettyAgent

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

    Enter the Agent profile realm
[ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ]
Enter the Agent Profile realm [/]:

  12. Enter the path to the password file you created as part of the pre-installation procedure:

    Enter the path to a file that contains the password to be used for identifying the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /tmp/pwd.txt

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

      Create arbitrary length keys with the agentadmin --key command.

  13. Review a summary of your responses and select how to continue:

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
…​
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.

  14. 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= /tmp/pwd.txt
AGENT_SIGNING_FILE=/tmp/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.

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the Jetty server where you plan to install the agent.

  3. Make sure that AM is running.

  4. Run the agentadmin command with the --useResponse option:

    $ agentadmin --install --acceptLicense --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

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the WebLogic server where you plan to install the agent.

  3. Make sure AM is running.

  4. 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. Use the --acceptLicense option to skip the prompt.

  5. Enter the path to the startWebLogic.sh file of the WebLogic domain where you want to install the agent:

    Enter the path to the location of the script used to start the WebLogic domain.
Please ensure that the agent is first installed on the admin server instance
before installing on any managed server instance.
[ ? : 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

  6. Enter the path to the WebLogic installation directory:

    Enter the WebLogic home directory
[ ? : Help, < : Back, ! : Exit ]
Enter the WebLogic home directory [/usr/local/bea/wlserver_10.0]:
/path/to/weblogic

  7. Enter the AM URL:

    Enter the URL where the AM server is running. Please include the deployment URI also as shown below:
(http://am.sample.com:58080/am)
[ ? : 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.

  8. Enter the agent URL:

    Enter the Agent URL. Please include the deployment URI also as shown below:
(http://agent1.sample.com:1234/agentapp)
[ ? : Help, < : Back, ! : Exit ]
Agent URL: \http://agent.example.com:80/app

  9. Enter the agent profile name created in AM as part of the pre-installation procedure:

    Enter the Agent profile name
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: WebLogicAgent

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

    Enter the Agent profile realm
[ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ]
Enter the Agent Profile realm [/]:

  11. Enter the path to the password file you created as part of the pre-installation procedure:

    Enter the path to a file that contains the password to be used for identifying the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /tmp/pwd.txt

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

      Create arbitrary length keys with the agentadmin --key command.

  12. Review a summary of your responses and select how to continue:

    $ /path/to/java_agents/weblogic_agent/bin/agentadmin --install --acceptLicense
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
...
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
...

  13. 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 the startWebLogic.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

  14. Start the WebLogic server.

  15. Deploy the /path/to/java_agents/weblogic_agent/etc/agentapp.war agent web application in WebLogic.

  16. 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= /tmp/pwd.txt
AGENT_SIGNING_FILE=/tmp/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.

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Make sure that the response file for the installation is ready, or create a response file, for example:

    $ agentadmin --install --saveResponse response-file

  3. Shut down the WebLogic server where you plan to install the agent.

  4. Make sure AM is running.

  5. Run the agentadmin command with the --useResponse option:

    $ agentadmin --install --acceptLicense --useResponse /path/to/response-file

  6. 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 the startWebLogic.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

  7. Start the WebLogic Server.

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

Install WebLogic Java Agent on administration and managed servers

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

  2. Prepare your protected web applications by adding the agent filter configuration as described in Configure the agent filter for a web application.

  3. Use the agentadmin command to install the agent either interactively, or silently on each server in the domain:

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

  5. Restart the managed servers.

Install WebSphere Java Agent

If you are using IBM Java, perform the procedure in Install WebSphere with IBM Java

Install WebSphere Java Agent interactively

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the WebSphere server where you plan to install the agent.

  3. Make sure AM is running.

  4. Run agentadmin --install to install the agent:

    $ /path/to/java_agents/websphere_agent/bin/agentadmin --install

    You are prompted to read and accept the software license agreement for the agent installation. Use the --acceptLicense option to skip the prompt.

  5. Enter the path to the configuration directory of the server instance for the WebSphere node:

    Enter the fully qualified path to the configuration directory of the Server
Instance for the WebSphere node.
[ ? : Help, ! : Exit ]
Enter the Instance Config Directory
[/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/<hostname>Node01Cell/nodes/<hostname>Node01/servers/server1]: **/path/to/WebSphere/AppServer/profiles/AppServ01/config/cells/DefaultCell01/nodes/DefaultNode01/servers/server1**

  6. Enter the name of the server instance where the agent will be installed:

    Enter the Server Instance name.
[ ? : Help, < : Back, ! : Exit ]
Enter the Server Instance name [server1]: **server1**

  7. Enter the path to the WebSphere install directory:

    Enter the WebSphere Install Root directory.
[ ? : Help, < : Back, ! : Exit ]
Enter the WebSphere Install Root directory
[/opt/IBM/WebSphere/AppServer]: **/path/to/WebSphere/AppServer**

  8. Enter the AM URL:

    Enter the URL where the AM server is running. Please include the deployment URI also as shown below:
(http://am.sample.com:58080/am)
[ ? : 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.

  9. Enter the agent URL:

    Enter the Agent URL. Please include the deployment URI also as shown below:
(http://agent1.sample.com:1234/agentapp)
[ ? : Help, < : Back, ! : Exit ]
Agent URL: \http://agent.example.com:80/app

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

    Enter the Agent profile realm
[ ? : Help, < : Back, ! : Exit, ^ : Accept Empty value ]
Enter the Agent Profile realm [/]:

  11. Enter the path to the password file you created as part of the pre-installation procedure:

    Enter the path to a file that contains the password to be used for identifying the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /tmp/pwd.txt

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

      Create arbitrary length keys with the agentadmin --key command.

  12. Review a summary of your responses and select how to continue:

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
...
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 WebSphere configuration,] copies the agent libraries to WebSphere’s external library directory, and sets up configuration and log directories for the agent.

  13. Restart the WebSphere server.

  14. Deploy the /path/to/java_agents/websphere_agent/etc/agentapp.war agent web application in WebSphere.

  15. 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 WebSphere 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
SERVER_INSTANCE_DIR= /path/to/WebSphere/AppServer/profiles/AppSrv01/config/cells/DefaultCell01/nodes/DefaultNode01/servers/server1
SERVER_INSTANCE_NAME= server1
HOME_DIRECTORY= /path/to/WebSphere/AppServer
AM_SERVER_URL= https://am.example.com:8443/am
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= WebSphereAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /tmp/pwd.txt
AGENT_SIGNING_FILE=/tmp/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.

Install WebSphere Java Agent silently

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Make sure that the response file for the installation is ready, or create a response file, for example:

    $ agentadmin --install --saveResponse response-file

  3. Shut down the WebSphere server where you plan to install the agent.

  4. Make sure AM is running.

  5. Run the agentadmin command with the --useResponse option:

    $ agentadmin --install --acceptLicense --useResponse /path/to/response-file

  6. Start the WebSphere server.

  7. Deploy the /path/to/java_agents/websphere_agent/etc/agentapp.war agent web application in WebSphere.

Install WebSphere Java Agent with IBM Java

The WebSphere Java Agent runs with IBM Java. To install the agent using IBM Java on platforms other than AIX, change the agentadmin script to use the IBM Java Cryptography Extensions (JCE).

Line breaks and continuation marker (\) characters have been added to the following examples to make them easier to understand. They are not required.

  1. Open the file bin/agentadmin for editing.

  2. Edit the line that calls the AdminToolLauncher jar file to move the $AGENT_OPTS environment variable before the classpath is set:

    Before:

    $JAVA_VM -classpath "$AGENT_CLASSPATH" $AGENT_OPTS \
         com.sun.identity.install.tools.launch.AdminToolLauncher $*

    After:

    $JAVA_VM $AGENT_OPTS -classpath "$AGENT_CLASSPATH" \
         com.sun.identity.install.tools.launch.AdminToolLauncher $*

  3. Save the file.

    You can now install the WebSphere Java Agent with IBM Java as described in Install the WebSphere Java Agent.

About WebSphere Network Deployment

When using WebSphere Application Server Network Deployment, you must install WebSphere Java 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.

Before installation, synchronize each server configuration with the profile saved by the Deployment Manager using the syncNode command. After agent installation, copy the server configuration for each node stored in server.xml to the corresponding Deployment Manager profile. After you have synchronized the configurations, you must restart the Deployment Manager for the Network Deployment.