Java Policy Agents 2023.3

Post-installation tasks

Review directories for configuration, logs, and POST data.

Each agent instance has a numbered directory, starting with Agent_001 for the first instance. The following directories are created under /path/to/java_agents/agent_type/Agent_n:

  • config: For information, see Configuration files.

  • logs: 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. The following log directories are created:

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

  • pdp: The directory to store POST data. The directory is created on installation, but used only when Enable POST Data Preservation and POST Data Preservation in Files or Cache are true.

Configure the agent filter for a web application

After installation, configure an agent filter to intercept inbound client requests and give them access to resources. The agent filter class is com.sun.identity.agents.filter.AmAgentFilter. The agent filter gives access based on the value of Agent Filter Mode Map.

Configure the agent filter in the web application’s web.xml file. For information about configuration options, see the documentation for your web application. For example, see Oracle’s Developing Web Applications for WebLogic Server.

Configure the agent filter first, before configuring other filters in web.xml. If several web applications run in the same container, configure an agent filter for each web application.

The following example protects every resource in the web application where it is configured:

<filter>
  <filter-name>Agent</filter-name>
  <display-name>AM Agent</display-name>
  <description>AM Agent Filter</description>
  <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>Agent</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>INCLUDE</dispatcher>
  <dispatcher>FORWARD</dispatcher>
  <dispatcher>ERROR</dispatcher>
</filter-mapping>

The following example protects an application that processes requests asynchronously:

<filter>
  <filter-name>Agent</filter-name>
  <display-name>AM Agent</display-name>
  <description>AM Agent Filter</description>
  <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
  <async-supported>true</async-supported>
</filter>

Configure the agent filter mode

By default, the agent filter uses the filter mode URL_POLICY. After installation, you can change the filter mode with the property Agent Filter Mode Map, or in the AM admin UI:

  1. In the AM admin UI, go to REALMS > realm name > Applications > Agents > Java, and select your Java Agent.

  2. On the Global tab, select Agent Filter Mode Map, and set the filter mode as follows:

    • To use URL_POLICY for all web applications in the web container, do not change the setting; this is the default.

    • To use SSO_ONLY for the BankApp web application, set these values:

  3. (Optional) In Agent Filter Mode, override the global mode for a specific context path:

    • Key: BankApp.

    • Value: Enter the mode name, for example URL_POLICY.

  4. Click Add, and save your changes.

Secure communication between the agent and AM

After installation, consider securing communication between the agent and AM.

  1. Configure AM to send cookies only when the communication channel is secure:

    1. In the AM admin UI, select REALMS > realm name > Applications > Agents > Java > agent name > SSO.

    2. Enable Transmit Cookies Securely.

  2. Import a CA certificate in the JDK truststore, usually at $JAVA_HOME/jre/lib/security/cacerts. The certificate should be the one configured for HTTPS connections in the AM container, or signed with the same CA root certificate. For example:

    $ keytool \
-import \
-trustcacerts \
-alias agentcert \
-file /path/to/cacert.pem \
-keystore $JAVA_HOME/jre/lib/security/cacerts

    Make sure that all containers where AM is installed trust the certificate stored in the JDK truststore, and that the JDK trusts the certificates stored on the containers where AM is installed.

  3. Add the following properties to the AgentBootstrap.properties file:

    • javax.net.ssl.trustStore, to specify the full path to the JDK truststore.

    • javax.net.ssl.trustStorePassword, to specify the password of the truststore.

      For example:

      javax.net.ssl.trustStore=/Library/Java/JavaVirtualMachines/jdk1.8.0_101.jdk/Contents/Home/jre/lib/security/cacerts
javax.net.ssl.trustStorePassword=changeit

      For backward-compatibility, you can also provide the truststore and the password to the agent by specifying them as Java properties in the container’s start-up sequence. For example, add them to Tomcat’s $CATALINA_OPS variable instead of specifying them in the AgentBootstrap.properties file:

      $ export CATALINA_OPTS="$CATALINA_OPTS \
-Djavax.net.ssl.trustStore=$JAVA_HOME/jre/lib/security/cacerts \
-Djavax.net.ssl.trustStorePassword=changeit"

  4. Restart the agent.

Copyright © 2010-2023 ForgeRock, all rights reserved.