Java Policy Agents 5.9.1

Post-Installation Tasks

Configure the Agent Filter for a Web Application

The Agent Filter is configured in the web application’s web.xml file. After installation, you must configure the agent filter.

To protect several web applications in the same container, configure the agent filter in each web application. If you configure additional filters in the web.xml file, make sure that the agent filter is defined first.

The agent filter configuration requires the following elements:

  • filter: Unique identifier of the filter and the filter class, containing the following elements:

    • filter-name. A string for the filter name, for example, Agent.

    • display-name. A string for the display name, for example, AM Agent. The container’s management console can use this string as an identifier for the filter.

    • description. A string for the description, for example, AM Agent Filter. The container’s management console can use this string as description for the filter.

    • filter-class. Agent filter class, com.sun.identity.agents.filter.AmAgentFilter.

  • filter-mapping. Resources protected by the filter, containing the following elements:

    • filter-name. The value must match the value of the filter-name element defined in the filter element.

    • url-pattern. The resources that the agent protects. For example, set the value to /* to protect every resource in the web application.

    • dispatcher. Optional. One or more dispatcher elements to protect the Java container dispatchers as well as the web application.

      For information about the container dispatchers, see container documentation.

Consider the following example configuration:

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

Configuring the Agent Filter Operation Mode

By default, the Agent Filter has the filter mode URL_POLICY. After installation, you can optionally change the filter mode. The following values are allowed:

Filter Mode Requires Authentication? Requires Authorization? Comments

URL_POLICY

Yes

Yes

AM performs the following tasks:

  • Issues an OIDC JWT to the client after successful authentication

    For more information about AM authentication mechanisms, see AM’s Authentication and Single Sign-On Guide.

  • Checks resource-based policies to evaluate whether the client can access the resource

    For more information about AM policies, see AM’s Authorization Guide.

SSO_ONLY

Yes

No

AM issues an OIDC JWT to the client after successful authentication.

NONE

No

No

Disables the agent filter from taking any action on incoming requests. If logging is enabled, the agent filter logs all incoming requests for auditing purposes.

J2EE_POLICY

-

-

This mode does not apply to Java Agents 5.9.1. For backward-compatibility, it is displayed in the AM agent profile page.

To change the filter mode, configure the agent property Agent Filter Mode Map, or follow this procedure:

  1. In the AM console, go to REALMS > Realm Name > Applications > Agents > Java, and select your Java Agent.

  2. In Agent Filter Mode Map on the Global tab, add a value for the filter mode, using the previous table.

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

    • Key: Enter the name of the context path, for example BankApp.

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

  4. Click Add, and save your changes.

Configure SSL Communication Between the Agent and AM

After installation, you can optionally configure SSL communication between the agent and AM.

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

    1. In the AM console, 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 either the same one configured for SSL purposes in the container where AM is installed, or one 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.