Java Policy Agents 5.9.1

About Java Agent

Java Agent is an Access Management add-on component that operates as a Policy Enforcement Point (PEP) or policy agent for web applications deployed on a Java container.

Java Agents intercept inbound requests to web applications. Depending on the filter mode configuration, Java Agents interact with AM to:

  • Ensure that clients provide appropriate authentication.

  • Enforce AM resource-based policies.

This chapter covers how Java Agents work and how their features can protect web applications.

Agent Components

Java Agent includes the following main components:

Agent Filter

Intercepts inbound client requests to a resource and processes them based on the filter mode of operation.

Agent Application

Deployed as agentapp.war, it is required for authentication and the cross-domain single sign-on (CDSSO) flow.

The following components are not part of Java Agent, but they play an important part in the agent operation:


A set of APIs required to interact with AM.

Agent Profile

A set of configuration properties that define the agent behavior. The agent profile can be stored in AM’s configuration store or as a text file local to the agent installation.

The following image shows the Java Agent components when the agent profile is stored in the AM configuration store:

Java Agent components

Agent Configuration

Java Agent uses the configuration files described in this section.

The files must be in a location defined by a property added to JAVA_OPTS. For example, in Tomcat, the agent can take the file location from bin/, as follows:

JAVA_OPTS="$JAVA_OPTS -Dopenam.agents.bootstrap.dir=/path/to/agents/agent/agent_instance/config"

This file defines bootstrap parameters. The following information is required in the file:

  • Private AM URL:

    Used for communication with AM, for example, to retrieve policy information or user information. The URL is assembled from the following properties, and is required, even if the agent never contacts AM:

  • Public AM URL:

    This URL must be provided by the user if the AM firewall rules distinguish between public and private URL. The agent uses this property to redirect the user’s browser to public-facing URLs for login. If it is not provided, the AM private URL is used.

  • Agent Profile:

  • Location of Agent Configuration Repository:

    Defines the agent configuration mode:

    • Local configuration mode

      The agent reads its configuration from When the agent is in this mode, it ignores changes made to the agent profile in AM.

      Depending on the configuration in the file, the agent might never need to contact AM. For example, if Autonomous mode is true, the agent runs independently of an AM instance.

    • Remote configuration mode (default)

      The agent ignores the configuration in, retains the retrieved bootstrap properties, and downloads the configuration from AM.

      When the first user request is made, the agent contacts AM to retrieve the agent configuration. If AM is unavailable, the request returns an HTTP 403 Permission denied.

This file defines agent configuration settings, and overrides any properties set in the bootstrap file.

If the value of Location of Agent Configuration Repository is LOCAL, the agent reads the file after If the value of Location of Agent Configuration Repository is REMOTE, the agent ignores this file.

In Java Agent 5.7 and earlier versions, this file was named

This file defines an encrypted password for the agent profile. For more information, see Encrypted Agent Password.

This file defines the key used to encrypt the agent password. For more information, see Encryption Key.

Changing the Agent Configuration

Change the agent configuration in the following ways:

Change the agent bootstrap configuration

Manually edit, and then restart the container running the agent.

Change the agent configuration in LOCAL mode

Manually edit the file, and set a value for Configuration Reload Interval.

The interval defines the number of seconds after which the agent reads the local property file, and reloads it if has changed since it was last read.

The value of Location of Agent Configuration Repository must be LOCAL.

Change the agent configuration in REMOTE mode

The agent is notified by the WebSocket mechanism when its configuration is changed in AM. The agent then re-reads its configuration from AM within a few seconds.

The value of Location of Agent Configuration Repository must be REMOTE.

Change the agent configuration on the AM console

Go to REALMS > Realm Name > Applications > agents > Java > agent name.

The value of Location of Agent Configuration Repository must be REMOTE.

Request Flow

When a client requests access to an application resource, the Java Agent intercepts the request. AM then validates the identity of the client, and their authorization to access the protected resource.

The following simplified data flow occurs when an unauthenticated client requests a resource protected by a Java Agent and AM. The flow assumes that requests must meet the requirements of an AM policy. For a detailed diagram, see Single Sign-On in AM’s Authentication and Single Sign-On Guide.


1 An unauthenticated client attempts to access a resource, and the agent intercepts the inbound request.

2 The agent evaluates whether the requested resource or the client IP address matches a not-enforced rule.

3-4 Alternate Flow. The requested resource or the client IP address matches a not-enforced rule. The agent allows access to the resource, and the client receives a response from The flow ends.

5 The agent creates a pre-authentication cookie to protect against reply attacks. The agent uses this cookie to track the authentication request to AM. Depending on the configuration, the agent may either issue a cookie to track all concurrent authentication requests, or may issue one cookie for each request.

6 The agent sets the AM login URL, which includes the goto parameter for the OAuth 2.0 authorize endpoint, and

7 The agent redirects the client to log in to AM.

8-12 The client authenticates to AM:

  • AM’s Authentication Service verifies the client credentials. AM creates an SSO token, and OIDC JWT with session information.

  • AM sends the client a self-submitting form with the OIDC JWT.

13 The client posts the self-submitting form to the agent endpoint, and the Java Agent consumes it.

14 The agent sets the cookie domain to the FQDN of the resource.

15 The client attempts to access the protected resource again, and the agent intercepts the request.

16 The agent contacts AM to validate the session contained in the OIDC JWT.

17 AM validates the session.

18 The agent contacts AM’s Policy Service, requesting a decision about whether the client is authorized to access the resource.

19 AM’s Policy Service returns ALLOW.

20 The agent writes the policy decision to the audit log.

21 The agent enforces the policy decision. Because the Policy Service returned ALLOW, the agent performs a pass-through operation to return the resource to the client.

22 The client accesses the resource.

Copyright © 2010-2023 ForgeRock, all rights reserved.