Java Policy Agents 5.9.1

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

  5. Enter the absolute 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

  6. 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 Apache HTTP Server As a Reverse Proxy Example.

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

  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://www.example.com:8080/agentapp

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

  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

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

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Tomcat Server Config Directory : /path/to/tomcat/conf

AM server URL : https://openam.example.com:8443/openam
$CATALINA_HOME environment variable : /path/to/tomcat

Agent URL : http://www.example.com:8080/agentapp
Agent Profile name : TomcatAgent
Agent Profile Realm : /
Agent Profile Password file name : /tmp/pwd.txt

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

...

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Bootstrap file location:
/path/to/java_agents/tomcat_agent/Agent_001/config/

Agent Configuration file location
/path/to/java_agents/tomcat_agent/Agent_001/config/

Agent Audit directory location:
/path/to/java_agents/tomcat_agent/Agent_001/logs/audit
Agent Debug directory location:
/path/to/java_agents/tomcat_agent/Agent_001/logs/debug

Install log file location:
/path/to/java_agents/tomcat_agent/installer-logs/audit/install.txt

Thank you for using AM Policy Agent

    After successful completion, the installer adds the agent configuration to the Tomcat configuration, and sets up configuration and log directories for the agent.

  13. Note the location of the configuration files and logs.

    Each agent instance that you install has a numbered configuration and logs directory. The first agent configuration and logs are located at java_agents/tomcat_agent/Agent_001/:

    config/AgentBootstrap.properties

    Used to bootstrap the agent, allowing it to connect to AM and download its configuration.

    config/AgentConfiguration.properties

    Used only if agent is in local configuration mode.

    logs/audit/

    Operational audit log directory, used only if remote logging to AM is disabled.

    logs/debug/

    The directory where the agent writes debug log files after startup.

    During agent startup, the location of the logs is based on the container which is being used. For example, bootstrap logs for Tomcat agents are written to catalina.out.

  14. Review Tomcat’s global web.xml file, your web application’s web.xml files, and configure the agent filter. For more information, see Configure the Agent Filter for a Web Application.

  15. Test the installation.

    If you completed the pre-installation setup, browse to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the resource you tried to access.

Install Tomcat 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/apache-tomcat/conf
AM_SERVER_URL= https://openam.example.com:8443/openam
CATALINA_HOME= /path/to/apache-tomcat
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= TomcatAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /tmp/pwd.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 Apache HTTP Server As a Reverse Proxy Example.

  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 Tomcat server where you plan to install the agent.

  4. Make sure that AM is running.

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

    $ agentadmin --install --acceptLicense --useResponse response-file

  6. Review Tomcat’s global web.xml file, your web application’s web.xml files, and configure the agent filter. For more information, see Configure the Agent Filter for a Web Application.

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 agentadmin --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://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 Apache HTTP Server As a Reverse Proxy Example.

  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://www.example.com:8080/agentapp

  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

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

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
JBoss home directory : /path/to/jboss/
JBoss deployment mode: standalone
Install agent as global module: true
AM server URL : https://openam.example.com:8443/openam

Agent URL : http://www.example.com:8080/agentapp
Agent Profile name : JBossAgent
Agent Profile Realm : /
Agent Profile Password file name : /tmp/pwd.txt

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

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Bootstrap file location:
/path/to/java_agents/jboss_agent/Agent_001/config/
Agent Configuration file location
/path/to/java_agents/jboss_agent/Agent_001/config/
Agent Audit directory location:
/path/to/java_agents/jboss_agent/Agent_001/logs/audit
Agent Debug directory location:
/path/to/java_agents/jboss_agent/Agent_001/logs/debug

Install log file location:
/path/to/java_agents/jboss_agent/installer-logs/audit/install.txt

Thank you for using AM Policy Agent

    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. Note the location of the configuration files and logs.

    Each agent instance that you install has a numbered configuration and logs directory. The first agent configuration and logs are located at java_agents/tomcat_agent/Agent_001/:

    config/AgentBootstrap.properties

    Used to bootstrap the agent, allowing it to connect to AM and download its configuration.

    config/AgentConfiguration.properties

    Used only if agent is in local configuration mode.

    logs/audit/

    Operational audit log directory, used only if remote logging to AM is disabled.

    logs/debug/

    The directory where the agent writes debug log files after startup.

    During agent startup, the location of the logs is based on the container which is being used. For example, bootstrap logs for Tomcat agents are written to catalina.out.

  16. To protect a web application in the container, configure the agent filter. For information, see Configure the Agent Filter for a Web Application.

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

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

  19. Test the installation.

    If you completed the pre-installation setup, browse to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the resource you tried to access.

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://openam.example.com:8443/openam
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= JBossAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /tmp/pwd.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 Apache HTTP Server As a Reverse Proxy Example.

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

  6. To protect a web application in the container, configure the agent filter. For information, see Configure the Agent Filter for a Web Application.

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

  8. 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 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 agentadmin --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://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 Apache HTTP Server As a Reverse Proxy Example.

  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://www.example.com:8080/agentapp

  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

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

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Jetty home directory (containing start.jar) : /path/to/jetty/home
Jetty Server etc directory : /path/to/jetty/etc
Jetty base directory (containing webapps subdirectory) which may be the same as your Jetty
home directory : /path/to/jetty/base
AM server URL : https://openam.example.com:8443/openam
Agent URL : https://www.example.com:8443/agentapp
Agent Profile name : JettyAgent
Agent Profile Realm : /
Agent Profile Password file name : /tmp/pwd.txt

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

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Bootstrap file location:
/path/to/java_agents/jetty_agent/Agent_001/config/
Agent Configuration file location
/path/to/java_agents/jetty_agent/Agent_001/config/
Agent Audit directory location:
/path/to/java_agents/jetty_agent/Agent_001/logs/audit
Agent Debug directory location:
/path/to/java_agents/jetty_agent/Agent_001/logs/debug

Install log file location:
/path/to/java_agents/jetty_agent/installer-logs/audit/install.txt

 Thank you for using AM Policy Agent

    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. Note the location of the configuration files and logs.

    Each agent instance that you install has a numbered configuration and logs directory. The first agent configuration and logs are located at java_agents/tomcat_agent/Agent_001/:

    config/AgentBootstrap.properties

    Used to bootstrap the agent, allowing it to connect to AM and download its configuration.

    config/AgentConfiguration.properties

    Used only if agent is in local configuration mode.

    logs/audit/

    Operational audit log directory, used only if remote logging to AM is disabled.

    logs/debug/

    The directory where the agent writes debug log files after startup.

    During agent startup, the location of the logs is based on the container which is being used. For example, bootstrap logs for Tomcat agents are written to catalina.out.

  15. To protect a web application in the container, configure the agent filter. For information, see Configure the Agent Filter for a Web Application.

  16. Test the installation.

    If you completed the pre-installation setup, browse to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the resource you tried to access.

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://openam.example.com:8443/openam
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= JettyAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /tmp/pwd.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 Apache HTTP Server As a Reverse Proxy Example.

  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 Jetty server where you plan to install the agent.

  4. Make sure that AM is running.

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

    $ agentadmin --install --acceptLicense --useResponse response-file

  6. To protect a web application in the container, configure the agent filter. For information, see Configure the Agent Filter for a Web Application.

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 agentadmin --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://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 Apache HTTP Server As a Reverse Proxy Example.

  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://www.example.com:8080/agentapp

  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

  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
-----------------------------------------------
Startup script location :
/Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh
WebLogic Server instance name : AdminServer
WebLogic home directory : /path/to/weblogic
AM server URL : https://openam.example.com:8443/openam

Agent URL : http://www.example.com:8080/agentapp
Agent Profile name : WebLogicAgent
Agent Profile Realm : /
Agent Profile Password file name : /tmp/pwd.txt

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

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Bootstrap file location:
/path/to/java_agents/weblogic_agent/Agent_001/config/
Agent Configuration file location
/path/to/java_agents/weblogic_agent/Agent_001/config/
Agent Audit directory location:
/path/to/java_agents/weblogic_agent/Agent_001/logs/audit
Agent Debug directory location:
/path/to/java_agents/weblogic_agent/Agent_001/logs/debug


Install log file location:
/path/to/java_agents/weblogic_agent/installer-logs/audit/install.txt

Thank you for using AM Policy Agent

  13. Note the location of the configuration files and logs.

    Each agent instance that you install has a numbered configuration and logs directory. The first agent configuration and logs are located at java_agents/tomcat_agent/Agent_001/:

    config/AgentBootstrap.properties

    Used to bootstrap the agent, allowing it to connect to AM and download its configuration.

    config/AgentConfiguration.properties

    Used only if agent is in local configuration mode.

    logs/audit/

    Operational audit log directory, used only if remote logging to AM is disabled.

    logs/debug/

    The directory where the agent writes debug log files after startup.

    During agent startup, the location of the logs is based on the container which is being used. For example, bootstrap logs for Tomcat agents are written to catalina.out.

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

  15. Start the WebLogic server.

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

  17. To protect a web application in the container, configure the agent filter. For information, see Configure the Agent Filter for a Web Application.

  18. Test the installation.

    If you completed the pre-installation setup, browse to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the resource you tried to access.

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://openam.example.com:8443/openam
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= WebLogicAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /tmp/pwd.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 Apache HTTP Server As a Reverse Proxy Example.

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

  9. To protect a web application in the container, configure the agent filter. For information, see Configure the Agent Filter for a Web Application.

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 agentadmin --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://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 Apache HTTP Server As a Reverse Proxy Example.

  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://www.example.com:8080/agentapp

  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

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

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Instance Config Directory :
/path/to/WebSphere/AppServer/profiles/AppServ01/config/cells/DefaultCell01/nodes/DefaultNode01/servers/server1

Instance Server name : server1
WebSphere Install Root Directory : /path/to/WebSphere/AppServer
AM server URL : https://openam.example.com:8443/openam

Agent URL : http://www.example.com:8080/agentapp
Agent Profile name : WebSphereAgent
Agent Profile Realm : /
Agent Profile Password file name : /tmp/pwd.txt

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

...

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Bootstrap file location:
/path/to/java_agents/websphere_agent/Agent_001/config/

Agent Configuration file location
/path/to/java_agents/websphere_agent/Agent_001/config/

Agent Audit directory location:
/path/to/java_agents/websphere_agent/Agent_001/logs/audit
Agent Debug directory location:
/path/to/java_agents/websphere_agent/Agent_001/logs/debug


Install log file location:
/path/to/java_agents/websphere_agent/installer-logs/audit/install.txt

Thank you for using AM Policy Agent

    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. Note the location of the configuration files and logs.

    Each agent instance that you install has a numbered configuration and logs directory. The first agent configuration and logs are located at java_agents/tomcat_agent/Agent_001/:

    config/AgentBootstrap.properties

    Used to bootstrap the agent, allowing it to connect to AM and download its configuration.

    config/AgentConfiguration.properties

    Used only if agent is in local configuration mode.

    logs/audit/

    Operational audit log directory, used only if remote logging to AM is disabled.

    logs/debug/

    The directory where the agent writes debug log files after startup.

    During agent startup, the location of the logs is based on the container which is being used. For example, bootstrap logs for Tomcat agents are written to catalina.out.

  14. Restart the WebSphere server.

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

  16. To protect a web application in the container, configure the agent filter. For information, see Configure the Agent Filter for a Web Application.

  17. Test the installation.

    If you completed the pre-installation setup, browse to a resource that the agent protects. AM redirects you to authenticate. After authentication, AM redirects you back to the resource you tried to access.

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://openam.example.com:8443/openam
AGENT_URL= http://www.example.com:8080/agentapp
AGENT_PROFILE_NAME= WebSphereAgent
AGENT_PROFILE_REALM= /
AGENT_PASSWORD_FILE= /tmp/pwd.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 Apache HTTP Server As a Reverse Proxy Example.

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

  6. Start the WebSphere server.

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

  8. To protect a web application in the container, configure the agent filter. For information, see Configure the Agent Filter for a Web Application.

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.

Copyright © 2010-2023 ForgeRock, all rights reserved.