--- title: Configure load balancers and reverse proxies description: 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: component: java-agents version: 2025.11 page_id: java-agents:user-guide:load-balancers-proxies canonical_url: https://docs.pingidentity.com/java-agents/2025.11/user-guide/load-balancers-proxies.html section_ids: client-identification: Identify clients behind load balancers and reverse proxies comms-am-agents: Agent - load balancer/reverse proxy - AM pre_authentication_cookie_signing: Pre-authentication cookie signing agents_ip_address_andor_fqdn: Agent's IP address and/or FQDN am_sessions_and_session_stickiness: AM sessions and session stickiness websockets: WebSockets am-forwarded-headers: Configure AM to use forwarded headers comms-clients-agents: Agent - load balancer/reverse proxy - client forward_clients_ip_address_andor_fqdns: Forward client's IP address and/or FQDNs use_sticky_load_balancing_with_post_data_preservation: Use sticky load balancing with POST data preservation override_protocol_host_and_port_after_tls_offloading: Override protocol, host, and port after TLS offloading match_fqdns_for_request_forwarding: Match FQDNs for request forwarding lb-different-protocol-and-port: Override protocol, host, and port lb-same-protocol-and-port: Map agent host name to the load balancer or reverse proxy host name lb-client-properties: Configure client identification properties lb-POST-data: Configure POST data preservation for load balancers or reverse proxies --- # 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.](_images/LB-proxy-AM-agent.svg) 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. ## Identify 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: * [Client IP Address Header](../properties-reference/org.forgerock.agents.http.header.containing.ip.address.html) * [Client Hostname Header](../properties-reference/org.forgerock.agents.http.header.containing.remote.hostname.html) 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. ### Pre-authentication cookie signing 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](about.html#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](glossary.html#def-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](../installation-guide/secure-connections.html#configure-HTTPS). * 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](about.html#agentkey-properties) file. 3. Install the next agent instance, and then replace the value of `org.forgerock.agents.cookie.signing.value` in [AgentKey.properties](about.html#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](#am-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](https://docs.pingidentity.com/pingam/8/setup-guide/configure-lb.html#configure-lb-stateful) 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-apache-server.html). | ### 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](https://www.rfc-editor.org/rfc/rfc7239.html). * Context path: AM's deployment URI. For example, `/am`. Leave the other fields empty. For more information, refer to [Base URL source](https://docs.pingidentity.com/pingam/8/am-reference/services-configuration.html#global-baseurl) 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](#lb-client-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](#lb-POST-data). ### 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.](_images/LB-different.svg) 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. ![Flow of a request through an agent.](_images/jee-agent-process-flow-load-balance.svg) In the following flow, the agent overrides the host, port, and protocol for subsequent redirects: ![Flow of a request through an agent.](_images/jee-agent-process-flow-load-balance2.svg) For this scenario, configure the agent as described in [To Override Protocol, Host, and Port](#lb-different-protocol-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.](_images/LB-same.svg) For this scenario, configure the agent as described in [To Map the Agent Host Name to the Load Balancer or Reverse Proxy Host Name](#lb-same-protocol-and-port). ### 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](glossary.html#def-remote-configuration-mode), but the steps mention properties for agents in [local configuration mode](glossary.html#def-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](glossary.html#def-remote-configuration-mode), but the steps mention properties for agents in [local configuration mode](glossary.html#def-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](glossary.html#def-remote-configuration-mode), but the steps mention properties for agents in [local configuration mode](glossary.html#def-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](glossary.html#def-remote-configuration-mode), but the steps mention properties for agents in [local configuration mode](glossary.html#def-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](../properties-reference/org.forgerock.agents.pdp.sticky.session.value.html) 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.