Java Agents 2023.11.2

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, refer to 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, refer to the documentation for your web application. For example, refer to 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.

Configure strategy for AM downtime

By default, if AM becomes unavailable at runtime, for example, due to network errors, the agent responds as follows:

  • Matches incoming requests against not-enforced rules

  • Resolves unmatched requests against the policy cache

  • Returns HTTP 503 for requests that don’t match cached results

The cache expires after the time defined by Policy Cache TTL.

To change the agent response to AM downtime, configure Strategy when AM unavailable.