Guide to installing and managing ForgeRock® Access Management Java agents. ForgeRock Access Management provides open source authentication, authorization, entitlement, and federation software.

Follow these steps to create agent administrator users for a realm:

1. In the AM console, navigate to Realms > Realm Name > Subjects.

2. Under Group click New... and create a group for agent administrators.

3. Switch to the Privileges tab for the realm, and click the name of the group you created.

4. Select Read and write access to all configured agents, and then Save your work.

5. Return to the Subjects tab, and under User create as many agent administrator users as needed.

6. For each agent administrator user, edit the user profile.

   Under the Group tab of the user profile, add the user to agent profile administrator group, and then Save your work.

7. Provide each system administrator who installs Java agents with their agent administrator credentials.

   When installing the Java agent with the --custom-install option, the system administrator can choose the option to create the profile during installation, and then provide the agent administrator user name and the path to a read-only file containing the agent administrator password. For silent installs, you can add the --acceptLicense option to auto-accept the software license agreement.

To configure how AM obtains the base URL of Java agents, use the Base URL Source service:

1. Log in to the AM console as an administrative user, such as amAdmin.

2. Navigate to Realms > Realm Name > Services.

3. Select Add a Service, select Base URL Source, and then select Create, leaving the fields empty.

4. Configure the service with the following properties:

   • Base URL Source: X-Forwarded-* headers

     This property allows AM to retrieve the base URL from the Forwarded header field in the HTTP request. The Forwarded HTTP header field is standardized and specified in RFC 7239.

   • Context path: AM's deployment uri. For example, /openam.

   Leave the rest of the fields empty.

   Tip

   For more information about the Base URL Source service, see Base URL Source in the ForgeRock Access Management Reference.

5. Save your changes.

Use the alternate Java agent URL properties to override the agent protocol, host, and port with that of the load balancer or reverse proxy.

This procedure explains how to do so for a centralized Java agent profile configured in the AM console. The steps also mention the properties for Java agent profiles that rely on local, file-based configurations:

1. Log in to the AM console as an administrative user with rights to modify the Java agent profile.

2. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced.

3. Set the Alternative Agent Host Name to that of the load balancer or reverse proxy. For example, lb.example.com.

   The equivalent property setting is com.sun.identity.agents.config.agent.host=lb.example.com.

4. Set the Alternative Agent Port number to that of the load balancer or proxy. For example, 80.

   The equivalent property setting is com.sun.identity.agents.config.agent.port=80.

5. Set the Alternative Agent Protocol to that of the load balancer or proxy. For example, http or https.

   The equivalent property setting is com.sun.identity.agents.config.agent.protocol=https.

6. Save your work.

7. Restart the Java container where the agent is installed.

When protocols and port numbers match, configure fully qualified domain name (FQDN) mapping.

This procedure explains how to do so for a centralized Java agent profile configured in the AM console. The steps also mention the properties for Java agent profiles that rely on local, file-based configurations:

1. Log in to the AM console as an administrative user with rights to modify the Java agent profile.

2. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name.

3. In the Global tab, enable FQDN Check.

   The equivalent property setting is com.sun.identity.agents.config.fqdn.check.enable=true.

4. Set the FQDN Default field to the fully qualified domain name of the load balancer or proxy, such as lb.example.com, rather than the protected container FQDN where the Java agent is installed.

   The equivalent property setting is com.sun.identity.agents.config.fqdn.default=lb.example.com.

5. Append the FQDN of the load balancer or proxy to the Agent Root URL for CDSSO field.

   The equivalent property setting is sunIdentityServerDeviceKeyValue[n]=lb.example.com.

6. Map the load balancer or proxy FQDN to the FQDN where the Java agent is installed in the FQDN Virtual Host Map key-pair map. For example, set the key agent.example.com (protected Java container) and a value lb.example.com (load balancer or proxy).

   The equivalent property setting is com.sun.identity.agents.config.fqdn.mapping[agent.example.com]=lb.example.com.

7. Save your work.

8. Restart the Java container where the agent is installed.

This procedure explains how to configure the client identification properties for a centralized Java agent profile configured in the AM console. The steps also mention the properties for Java agent profiles that rely on local, file-based configurations:

1. Log in to the AM console with a user that has permissions to modify the Java agent profile.

2. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced.

3. (Optional) In the Client IP Address Header field, configure the name of the header containing the IP address of the client. For example, X-Forwarded-For.

   Configure this property if your AM policies are IP address-based, you configured the agent for not-enforced IP rules, or if you configured the agent to take any decision based on the client's IP address.

   The equivalent property setting is com.sun.identity.agents.config.client.ip.header=X-Forwarded-For.

4. (Optional) In the Client Hostname Header field, configure the name of the header containing the FQDN of the client. For example, X-Forwarded-Host.

   Configure this property if your AM policies are URL-based, you configured the agent for not-enforced URL rules, or if you configured the agent to take any decision based on the client's URL.

   The equivalent property setting is com.sun.identity.agents.config.client.hostname.header=X-Forwarded-Host.

5. Save your changes.

1. Log in to the AM console with a user that has permissions to modify the Java agent profile.

2. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced.

3. Decide whether the Java agent should create a cookie or append a string to the URL to assist with sticky load balancing.

   In the PDP Stickysession mode drop-down menu, configure one of the following options:

   • Cookie. The Java agent will create a cookie for POST data preservation session stickiness. The contents of the cookie is configured in the next step.

   • URL. The Java agent will append to the URL a string specified in the next step.

   The equivalent property setting is org.forgerock.agents.pdp.sticky.session.mode=[Cookie|URL].

4. In the PDP Sticky Session Key Value property, configure a key-pair value separated by the = character.

   For example, specifying lb=myserver either sets a cookie called lb with myserver as a value, or appends lb=myserver to the URL query string.

   The equivalent property setting is org.forgerock.agents.pdp.sticky.session.value=lb=myserver.

5. Save your changes.

6. Configure your load balancer or reverse proxy to ensure session stickiness when the cookie or URL query parameter are present.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

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

2. Make sure AM is running.

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

   $ /path/to/java_agents/tomcat_agent/bin/agentadmin --install --acceptLicense

   1. When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

   2. Enter the path to the Tomcat configuration folder. For example, /path/to/apache-tomcat/conf.

      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-6.0.14/conf]: /path/to/apache-tomcat/conf

   3. Enter the AM URL. For example, https://openam.example.com:8443/openam.

      To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

      Note

      If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

      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
      

   4. Enter the $CATALINA_HOME environment variable specifying the path to the root of the Tomcat server. For example, /path/to/apache-tomcat.

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

   5. Enter the agent URL. For example, http://www.example.com:8080/agentapp.

      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

   6. Enter the agent profile name that you created in AM as part of the pre-installation procedure. For example, TomcatAgent.

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

   7. Enter the realm in which the specified agent profile exists.

      Press ENTER to accept the default value of /, signifying the top-level realm.

      Note

      If you specify the Accept Empty value (^) option, the top-level realm is assumed.

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

   8. Enter the path to the password file you created as part of the pre-installation procedure. For example, /tmp/pwd.txt.

      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

4. Review a summary of your responses and select an action to continue: install, go back a step, start over, or exit from the install:

   -----------------------------------------------
   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/
   AgentBootstrap.properties
   Agent Configuration file location
   /path/to/java_agents/tomcat_agent/Agent_001/config/
   AgentConfiguration.properties
   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

   Upon successful completion, the installer adds the agent configuration to the Tomcat configuration, and also set up the configuration and log directories for the agent.

5. Take note of the configuration files and log locations.

   Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory 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

   Only used if you configured the agent to use local configuration.

   logs/audit/

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

   logs/debug/

   Directory for the debugging file. Use for troubleshooting.

6. Review Tomcat's global web.xml file and your application's web.xml files and configure the agent filter.

7. (Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

1. Review the information in "Before You Install".

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

3. Make sure that AM is running.

4. Make sure you have a response file ready. For example, response-file. For more information, see "Installing the Tomcat Java Agent Silently".

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

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

6. Review Tomcat's global web.xml file and your application's web.xml files and configure the agent filter.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

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

2. Make sure AM is running.

3. Run agentadmin --install to install the JBoss Java agent:

   $ /path/to/java_agents/jboss_agent/bin/agentadmin --install --acceptlicense

   1. When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

   2. Enter the path to the JBoss installation directory. For example, /path/to/jboss.

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

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

      • standalone

      • domain

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

   5. Decide whether to deploy the agent as a global JBoss module. To include application-specific modules, enter false.

      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

   6. Enter the AM URL. For example, https://openam.example.com:8443/openam.

      To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

      Note

      If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

      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

   7. Enter the agent URL. For example, http://www.example.com:8080/agentapp.

      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

   8. Enter the agent profile name that you created in AM as part of the pre-installation procedure. For example, JBossAgent.

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

   9. Enter the realm in which the specified agent profile exists.

      Press ENTER to accept the default value of /, signifying the top-level realm.

      Note

      If you specify the Accept Empty value (^) option, the top-level realm is assumed.

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

   10. Enter the path to the password file that you created as part of the pre-installation procedure. For example, /tmp/pwd.txt.

       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

4. Review a summary of your responses and select an action to continue: install, go back a step, start over, or exit from the install:

   -----------------------------------------------
   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/
    AgentBootstrap.properties
   Agent Configuration file location
   /path/to/java_agents/jboss_agent/Agent_001/config/
    AgentConfiguration.properties
   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

   Upon successful completion, the installer updates the JBoss configuration, adds the Java agent application under JBOSS_HOME/server/standalone/deployments, and also sets up configuration and log directories for the Java agent.

5. Take note of the configuration files and log locations.

   Each Java agent instance that you install on the system has its own numbered configuration and logs directory. The first Java agent instance configuration files and logs are thus located under the directory java_agents/jboss_agent/Agent_001/:

   config/AgentBootstrap.properties

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

   config/AgentConfiguration.properties

   Only used if you configured the Java agent to use local configuration.

   logs/audit/

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

   logs/debug/

   Debug directory where the debug file resides. Useful in troubleshooting Java agent issues.

6. To protect an application in the container, configure the agent filter.

7. (Optional) If you responded false to the Deploy the policy agent as a global JBoss module question during the installation process, perform the following steps:

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

      Dependencies: org.forgerock.openam.agent

   2. Create a /path/to/protected/app/WEB-INF/jboss-deployment-structure.xml file 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>

8. (Optional) If you responded domain to the Enter the name of the deployment mode question during the installation process, you must manually deploy the java_agents/jboss_agent/etc/agentapp.war file to JBoss.

   The reason manual deployment is required when running JBoss in domain mode is that the agent installer uses auto-deployment capabilities provided by the JBoss deployment scanner. The deployment scanner is used only in standalone mode. When running JBoss in standalone mode, it is not necessary to manually deploy the agentapp.war file.

9. (Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

1. Review the information in "Before You Install" before proceeding.

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

3. Make sure AM is running.

4. Make sure you have a response file ready. For example, response-file. For more information, see "Installing the JBoss Java Agent Silently".

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

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

6. To protect an application in the container, configure the agent filter.

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

   Dependencies: org.forgerock.openam.agent

8. If you configured the INSTANCE_NAME variable as domain in the response file, you must manually deploy the java_agents/jboss_agent/etc/agentapp.war file to JBoss.

   The reason manual deployment is required when running JBoss in domain mode is that the agent installer uses auto-deployment capabilities provided by the JBoss deployment scanner. The deployment scanner is used only in standalone mode. When running JBoss in standalone mode, it is not necessary to manually deploy the agentapp.war file.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

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

2. Make sure AM is running.

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

   $ /path/to/java_agents/jetty_agent/bin/agentadmin --install --acceptLicense

   1. When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

   2. Enter the absolute path to the root of the Jetty installation. For example, /path/to/jetty/home. This is the equivalent of the JETTY_HOME environment variable for Jetty.

      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

   3. Enter the absolute path to the Jetty configuration directory. For example, /path/to/jetty/etc.

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

   4. Enter the absolute path to the Jetty base directory. For example, /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.

      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

   5. Enter the AM URL. For example, https://openam.example.com:8443/openam.

      To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

      Note

      If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

      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

   6. Enter the agent URL. For example, http://www.example.com:8080/agentapp.

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

   7. Enter the agent profile name that you created in AM as part of the pre-installation procedure. For example, JettyAgent.

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

   8. Enter the realm in which the specified agent profile exists.

      Press ENTER to accept the default value of /, signifying the top-level realm.

      Note

      If you specify the Accept Empty value (^) option, the top-level realm is assumed.

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

   9. Enter the path to the password file you created as part of the pre-installation procedure. For example, /tmp/pwd.txt.

      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

4. Review a summary of your responses and select an action to continue: install, go back a step, start over, or exit from the installer:

   -----------------------------------------------
   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/
    AgentBootstrap.properties
   Agent Configuration file location
   /path/to/java_agents/jetty_agent/Agent_001/config/
    AgentConfiguration.properties
   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

   Upon successful completion, the installer updates Jetty's start.jar to reference the agent, sets up the agent web application, and also sets up configuration and log directories for the agent.

5. Take note of the configuration files and log locations.

   Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory java_agents/jetty_agent/Agent_001/:

   config/AgentBootstrap.properties

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

   config/AgentConfiguration.properties

   Only used if you configured the Java agent to use local configuration.

   logs/audit/

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

   logs/debug/

   Directory for the debugging file. Use for troubleshooting.

6. To protect an application in the container, configure the agent filter.

7. (Optional) If you have a policy configured, you can test the agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

1. Check the information in "Before You Install".

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

3. Make sure that AM is running.

4. Make sure you have a response file ready. For example, response-file. For more information, see "Installing the Jetty Java Agent Silently".

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

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

6. To protect an application in the container, configure the agent filter.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

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

2. Make sure AM is running.

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

   $ /path/to/java_agents/weblogic_agent/bin/agentadmin --install --acceptlicense

   1. When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

   2. Enter the path to the startWebLogic.sh file of the WebLogic domain where you want to install the agent. For example, /Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh.

      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

   3. Enter the path to the WebLogic installation directory. For example, /path/to/weblogic.

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

   4. Enter the AM URL. For example, https://openam.example.com:8443/openam.

      To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

      Note

      If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

      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 balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

   5. Enter the agent URL. For example, http://www.example.com:8080/agentapp.

      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

   6. Enter the agent profile name that you created in AM as part of the pre-installation procedure. For example, WebLogicAgent.

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

   7. Enter the realm in which the specified agent profile exists.

      Press ENTER to accept the default value of /, signifying the top-level realm.

      Note

      If you specify the Accept Empty value (^) option, the top-level realm is assumed.

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

   8. Enter the path to the password file that you created as part of the pre-installation procedure. For example, /tmp/pwd.txt.

      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

4. Review a summary of your responses and select an action to continue: install, go back a step, start over, or exit from the install:

   $ /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/
    AgentBootstrap.properties
   Agent Configuration file location
   /path/to/java_agents/weblogic_agent/Agent_001/config/
    AgentConfiguration.properties
   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

5. Take note of the configuration files and log locations.

   Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory java_agents/weblogic_agent/Agent_001/:

   config/AgentBootstrap.properties

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

   config/AgentConfiguration.properties

   Only used if you configured the Java agent to use local configuration.

   logs/audit/

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

   logs/debug/

   Debug directory where the debug file resides. Useful in troubleshooting agent issues.

6. The agent requires sourcing before it will work properly. There are two ways to source:

   • Manually source the file containing the agent environment settings for WebLogic before starting the application server.

     $ . /path/to/setAgentEnv_AdminServer.sh

   • Or edit the startWebLogic.sh script to set the sourcing needed for the agent, by adding these lines after the code block shown. Add the setAgentEnv_AdminServer.sh line to the following location in the file. The drawback to this approach is that it could be overwritten, as noted in the file:

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

   Note

   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>> <><> <> <1360800613441>
   <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 application in WebLogic.

9. To protect an application in the container, configure the agent filter.

10. (Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

1. Review the information in "Before You Install".

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

3. Make sure AM is running.

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

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

5. The agent requires sourcing before it will work properly. There are two ways to source:

   • Manually source the file containing the agent environment settings for WebLogic before starting the application server.

     $ . /path/to/setAgentEnv_AdminServer.sh

   • Or edit the startWebLogic.sh script to set the sourcing needed for the agent, by adding these lines after the code block shown. Add the setAgentEnv_AdminServer.sh line to the following location in the file. The drawback to this approach is that it could be overwritten, as noted in the file:

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

6. Start the WebLogic Server.

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

8. To protect an application in the container, configure the agent filter.

For multi-server WebLogic domains, install the Java agent as follows:

1. If servers are on different hosts, create agent profiles for each server where you plan to install the agent.

   The steps are described under "Installing the WebLogic Java Agent".

2. Prepare your protected web applications by adding the agent filter configuration as described in "Configuring the Agent Filter for an Application".

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

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.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

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

2. Make sure AM is running.

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

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

   1. When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

   2. Enter the path to the configuration directory of the server instance for the WebSphere node. For example, /path/to/WebSphere/AppServer/profiles/AppServ01/config/cells/DefaultCell01/nodes/DefaultNode01/servers/server1.

      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

   3. Enter the name of the server instance where the agent will be installed. For example, server1.

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

   4. Enter the path to the WebSphere install directory. For example, /path/to/WebSphere/AppServer.

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

   5. Enter the AM URL. For example, https://openam.example.com:8443/openam.

      To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

      Note

      If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

      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

   6. Enter the agent URL. For example, http://www.example.com:8080/agentapp.

      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

   7. Enter the agent profile name that you created in AM as part of the pre-installation procedure. For example, WebSphereAgent.

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

   8. Enter the realm in which the specified agent profile exists.

      Press ENTER to accept the default value of /, signifying the top-level realm.

      Note

      If you specify the Accept Empty value (^) option, the top-level realm is assumed.

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

   9. Enter the path to the password file that you created as part of the pre-installation procedure. For example, /tmp/pwd.txt.

      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

4. Review a summary of your responses and select an action to continue: install, go back a step, start over, or exit:

   -----------------------------------------------
   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/
    AgentBootstrap.properties
   Agent Configuration file location
   /path/to/java_agents/websphere_agent/Agent_001/config/
    AgentConfiguration.properties
   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

   Upon successful completion, the installer updates the WebSphere configuration, copies the agent libraries to WebSphere's external library directory, and also sets up configuration and log directories for the agent.

5. Take note of the configuration files and log locations.

   Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory java_agents/websphere_agent/Agent_001/:

   config/AgentBootstrap.properties

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

   config/AgentConfiguration.properties

   Only used if you configured the Java agent to use local configuration.

   logs/audit/

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

   logs/debug/

   Debug directory where the debug file resides. Useful in troubleshooting agent issues.

6. Restart the WebSphere server.

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

8. To protect an application in the container, configure the agent filter.

9. (Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

Perform the following steps to create the configuration required by the Java agent before installing it:

1. Create at least one policy in AM to protect resources with the agent, as described in the procedure Configuring Policies.

2. Create an agent profile in AM, required by the Java agent to connect and communicate with AM. For more information, see "Creating Agent Profiles".

3. Ensure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the Java agents is not the default test key pair. For more information, see "Configuring AM Servers to Communicate With Java Agents".

4. Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in the ForgeRock Access Management Security Guide.

5. Consider the communication between the agents and the AM servers, and between the agents and the clients when installing agents in environments with load balancers and/or reverse proxies. For more information, see "Configuring Environments With Load Balancers and Reverse Proxies".

6. Create a text file containing only the password specified when creating the agent profile, and protect it:

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt

   C:\> echo password > pwd.txt

   In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

1. Check the information in "Before You Install".

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

3. Make sure AM is running.

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

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

5. Start the WebSphere server.

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

7. To protect an application in the container, configure the agent filter.

8. (Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

1. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name.

2. On the Global tab, change the mode in the Agent Filter Mode (com.sun.identity.agents.config.filter.mode) property:

   • To set the global filter mode, enter the mode name in the Value field, for example SSO_ONLY, and then click Add.

   • To override the filter mode for a particular context path, enter the name of the context path in the Key field, for example BankApp, enter the mode name in the Value field, for example URL_POLICY, and then click Add.

   Setting the Agent Filter Mode

   
   
   

3. Save your changes.