Java Agents 2023.11.1

Configure load balancers and reverse proxies

Most environments deploy a load balancer and reverse proxy between the agent and clients, and another between the agent and AM, as shown in the following diagram:

Simplified diagram showing reverse proxies and load balancers configured in an environment with Java Agents.

The reverse proxy and the load balancer can be the same entity. In complex environments, multiple load balancers and reverse proxies can be deployed in the network.

Identifying clients behind load balancers and reverse proxies

When a load balancer or reverse proxy is situated in the request path between the agent and a client, the agent does not have direct access to the IP address or hostname of the client. The agent cannot identify the client.

For load balancers and reverse proxies that support provision of the client IP and hostname in HTTP headers, configure the following properties:

When there are multiple load balancers or reverse proxies in the request path, the header values can include a comma-separated list of values, where the first value represents the client, as in client,next-proxy,first-proxy.

Agent - load balancer/reverse proxy - AM

When a reverse proxy is situated between the agent and AM, it protects the AM APIs.

When a load balancer is situated between the agent and AM, it regulates the load between different instances of AM.

Consider the points in this section when installing Java Agent in an environment where AM is behind a load balancer or a reverse proxy.

During installation, the agent requests the path to a file containing the cookie signing key, and then uses the key to configure the property org.forgerock.agents.cookie.signing.value in AgentKey.properties. If the path is empty, cookie signing is disabled.

The key must be at least 64 characters long. If it is shorter, the agent rejects it and leaves cookies unsigned. For security, use a key of at least 80 characters.

In deployments with multiple agent instances, use the same cookie signing key for each instance. Share a cookie signing key between agent instances as follows:

  • If agent instances can share the signing key file, specify the same file for each agent installation.

  • If agent instances are in remote configuration mode, set the property org.forgerock.agents.cookie.signing.value in the Advanced tab of the AM admin UI.

    When storing shared keys in AM Secure communication between the agent and AM.

  • Manually update the agent configuration, as defined in the following procedure:

  1. Install the first agent instance.

  2. Note the value of org.forgerock.agents.cookie.signing.value in the AgentKey.properties file.

  3. Install the next agent instance, and then replace the value of org.forgerock.agents.cookie.signing.value in AgentKey.properties with the value from the first instance.

  4. Restart the instance.

Agent’s IP address and/or FQDN

The load balancer or reverse proxy conceals the IP addresses and FQDNs of the agent and of AM. Consequently, AM cannot determine the agent base URL.

Do the following to prevent problems during installation, or with redirection using the goto parameter:

  • Configure the load balancer or reverse proxy to forward the agent IP address and/or FQDN in a header.

  • Configure AM to recover the forwarded headers. For more information, refer to Configuring AM to use forwarded headers.

  • Install the agent using the IP address or FQDN of the load balancer or reverse proxy as the point of contact for the AM site.

AM sessions and session stickiness

Improve the performance of policy evaluation by setting AM’s sticky cookie (by default, amlbcookie) to the AM’s server ID. For more information, refer to Configuring site sticky load balancing in AM’s Setup guide.

When configuring multiple agents, consider the impact on sticky load balancer requirements of using one or multiple agent profiles:

  • If the agents are configured with multiple agent profiles, configure sticky load balancing. This is because the agent profile name is contained in the OpenID Connect JWT, used by the agent and AM for communication. Without session stickiness, there is no way to make sure that the appropriate JWT ends in the appropriate agent instance.

  • If multiple agents are configured with the same agent profile, decide whether to configure sticky load balancing depending on other requirements of your environment.

WebSockets

For communication between the agents and the AM servers, the load balancers and reverse proxies must support the WebSocket protocol. For more information, refer to the load balancer or proxy documentation.

For an example of how to configure Apache HTTP as a reverse proxy, refer to Configure an Apache HTTP Server as a reverse proxy.

Configure AM to use forwarded headers

When a load balancer or reverse proxy is situated between the agent and AM, configure AM to recover the forwarded headers that expose the agents' real IP address or FQDN.

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

  2. Select Realms > realm name > Services.

  3. Select Add a Service > Base URL Source > 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, /am.

      Leave the other fields empty.

      For more information, refer to Base URL source in AM’s Reference.

  5. Save your changes.

Agent - load balancer/reverse proxy - client

When a reverse proxy is situated between the agent and client, it renders anonymous the client traffic that enters the network.

When a load balancer is situated between the agent and client, it regulates the load between the agents and the containers.

Consider the points in this section when installing Java Agent in an environment where clients are behind a load balancer or a reverse proxy:

Forward client’s IP address and/or FQDNs

The load balancer or reverse proxy conceals the IP addresses and FQDNs of the agent and clients. Consequently, the agent cannot determine the client base URL.

Configure the load balancer or reverse proxy to forward the client IP address and/or the client FQDN in a header. Failure to do so prevents the agent from performing policy evaluation, and applying not-enforced and conditional login/logout rules.

For more information, refer to Configuring client identification properties.

Use sticky load balancing with POST data preservation

For POST data preservation, use sticky load balancing to ensure that the client always hits the same agent and, therefore, their saved POST data.

Agents provide properties to set either sticky cookie or URL query string for load balancers and reverse proxies.

For more information, refer to Configuring POST Data Preservation for Load Balancers or Reverse Proxies.

Override protocol, host, and port after TLS offloading

The load balancer or reverse proxy performs TLS offloading, terminating the TLS traffic and converting the requests reaching the Java container to HTTP. This reduces the load on the protected containers, because the public key is usually processed by a hardware accelerator.

The following diagram shows the agent connected to a client through a reverse proxie and load balancer. The agent connection to the reverse proxy and load balancer is on HTTP and port 80. The client connection is on HTTPS and port 443.

Simplified diagram showing reverse proxies and load balancers using different protocol, port, and FQDN than the Java containers.

After TLS offloading, the host, port, and protocol of the request is changed to match the request received by the agent; it no longer matches the request from the client, as shown in the following data flow. The agent uses this URL for the redirect_url from the OAuth 2.0 flow, which causes the request to fail.

jee-agent-process-flow-load-balance

In the following flow, the agent overrides the host, port, and protocol for subsequent redirects:

jee-agent-process-flow-load-balance2

For this scenario, configure the agent as described in To Override Protocol, Host, and Port.

Match FQDNs for request forwarding

The load balancer or reverse proxy forwards requests and responses between clients and protected Java containers only. In this case, ports and protocols configured in the Java container match those on the load balancer or reverse proxy, but FQDNs do not.

The following diagram illustrates this scenario:

Simplified diagram showing reverse proxies and load balancers using the same protocol and port than the Java containers.

For this scenario, configure the agent as described in To Map the Agent Host Name to the Load Balancer or Reverse Proxy Host Name.

Override protocol, host, and port

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

The agent in this example is in remote configuration mode, but the steps mention properties for agents in local configuration mode.

Agent configuration for TLS offloading prevents FQDN checking and mapping. Consequently, URL rewriting and redirection do not work correctly when the agent is accessed directly and not through the load balancer or proxy. This should not be a problem for client traffic, but could be a problem for web applications accessing the protected container directly, from behind the load balancer.

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

  2. Select Realms > realm name > Applications > Agents > Java > agent name > Advanced.

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

    The equivalent property setting is org.forgerock.agents.agent.hostname=lb.example.com.

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

    The equivalent property setting is org.forgerock.agents.agent.port=80.

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

    The equivalent property setting is org.forgerock.agents.agent.protocol=https.

  6. Save your work.

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

Map agent host name to the load balancer or reverse proxy host name

When protocols and port numbers match, configure FQDN mapping.

The agent in this example is in remote configuration mode, but the steps mention properties for agents in local configuration mode.

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

  2. Select Realms > realm name > Applications > Agents > Java > agent name.

  3. In the Global tab, enable FQDN Check.

    The equivalent property setting is org.forgerock.agents.fqdn.check.enabled=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 org.forgerock.agents.fqdn.default=lb.example.com.

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

  6. Map the load balancer or proxy FQDN to the FQDN where the 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 org.forgerock.agents.fqdn.map[agent.example.com]=lb.example.com.

  7. Save your work.

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

Configure client identification properties

After configuring proxies or load balancers to forward the client FQDN and/or IP address, configure the agents to check the appropriate headers.

This procedure explains how to configure the client identification properties.

The agent in this example is in remote configuration mode, but the steps mention properties for agents in local configuration mode.

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

  2. Select Realms > realm name > Applications > Agents > Java > agent name > Advanced.

  3. 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 org.forgerock.agents.http.header.containing.ip.address=X-Forwarded-For.

  4. 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 org.forgerock.agents.http.header.containing.remote.hostname=X-Forwarded-Host.

  5. Save your changes.

Configure POST data preservation for load balancers or reverse proxies

Configure the load balancer or reverse proxy and the agents for session stickiness.

The agent in this example is in remote configuration mode, but the steps mention properties for agents in local configuration mode.

  1. Log in to the AM admin UI as a user with permission to modify the agent profile.

  2. Select Realms > realm name > Applications > Agents > Java > agent name > Advanced.

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

    In PDP Sticky session mode, configure one of the following options:

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

    • URL: The agent appends 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 POST Data Preservation 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.