--- 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: web-agents version: 2025.11 page_id: web-agents:user-guide:load-balancers-proxies canonical_url: https://docs.pingidentity.com/web-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 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 lb-same-protocol-and-port: Map the agent host name to a load balancer or reverse proxy lb-different-protocol-and-port: Override the request protocol, host, and port bypass_load_balancers_to_directly_access_agents: Bypass load balancers to directly access agents lb-client-properties: Configure client identification properties lb-POST-data: Configure POST Data Preservation for load balancers or reverse proxies lb-POST-data-121: Map one agent profile to one agent instance when POST data preservation is enabled lb-POST-data-12all: Map one agent profile to multiple agent instances when POST data preservation is enabled --- # 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 web agents.](_images/LB-proxy-AM-agent.svg)Figure 1. Environments with load balancers and reverse proxies 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/com.sun.identity.agents.config.client.ip.header.html) * [Client Hostname Header](../properties-reference/com.sun.identity.agents.config.client.hostname.header.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 can be used to protect the AM APIs. When a load balancer is situated between the agent and AM, it can be used to regulate the load between different instances of AM. Consider the points in this section when installing Web Agent in an environment where AM is behind a load balancer or a reverse proxy. ### 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. To prevent problems during installation or redirection, do the following: * 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. Learn more in [Configure 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/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 agents are configured with multiple agent profiles, configure sticky load balancing. The agent profile name is contained in the OpenID Connect JWT, used by the agent and AM for communication. Without session stickiness, it is not possible to make sure the appropriate JWT ends in the appropriate agent instance. To have multiple agent profiles without sticky load balancing, disable validation of the `aud` claim in the session ID token. Either enable [Disable Audience Claim Validation](../properties-reference/com.forgerock.agents.jwt.aud.disable.html), or configure [Agent Profile ID Allow List](../properties-reference/com.forgerock.agents.jwt.aud.whitelist.html). For security reasons, agents should validate all claims in session ID tokens. Therefore, use this approach sparingly and mostly for migrations. * 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 AM servers, the load balancers and reverse proxies must support the WebSocket protocol. Learn more in the load balancer or proxy documentation. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For configuration examples, refer to [Apache as a reverse proxy](../installation-guide/apache.html#configure-apache-server) and [NGINX as a reverse proxy](../installation-guide/apache.html#nginx-reverse-proxy-server). | ### 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. To configure how AM obtains the base URL of web agents, use the Base URL Source service: 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, and create a default service, leaving the fields empty. 4. Configure the service with the following properties, leaving the other fields empty: * 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 specified in [RFC 7239: Forwarded HTTP Extension](https://www.rfc-editor.org/rfc/rfc7239). * Context path: AM's deployment URI. For example, `/am`. Learn more in [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 can be used to anonymize the client traffic that enters the network. When a load balancer is situated between the agent and client, it can be used to regulate the load between the agents and the web application servers. Consider the points in this section when installing Web 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. Learn more in [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 after login the client hits the same agent as before and can therefore get their saved POST data. Agents provide properties to set either sticky cookie or URL query string for load balancers and reverse proxies. Learn more in [Configure POST Data Preservation for Load Balancers or Reverse Proxies](#lb-POST-data). ### Map the agent host name to a load balancer or reverse proxy In the following diagram, the agent and load balancer/reverse proxy use the same protocol and port, but different FQDNs: ![Simplified diagram showing reverse proxies and load balancers using the same protocol and port than the web servers.](_images/LB-same.svg)Figure 2. Same protocol and port, different FQDN Map the host name of the agent to that of the load balancer or reverse proxy. 1. Log in to the AM admin UI as an administrative user with rights to modify the web agent profile. 2. Go to Realms > *Realm Name* > Applications > Agents > Web > *Agent Name*. 3. Set the following options in the Global tab: * FQDN Check: Enable The equivalent property setting is [Enable FQDN Check](../properties-reference/com.sun.identity.agents.config.fqdn.check.enable.html) = `true`. * FQDN Default: Set to the FQDN of the load balancer or proxy, for example `lb.example.com`. Do not set it to the protected server FQDN where the agent is installed. The equivalent property setting is [FQDN Default](../properties-reference/com.sun.identity.agents.config.fqdn.default.html) = `lb.example.com`. * Agent Root URL for CDSSO: Set to the FQDN of the load balancer or proxy, for example `https://lb.example.com:80/`. The equivalent property setting is [Agent Root URL for CDSSO](../properties-reference/sunIdentityServerDeviceKeyValue.html) = `lb.example.com`. * FQDN Virtual Host Map: Map the load balancer or proxy FQDN to the FQDN where the agent is installed. For example, * Key: `agent.example.com` (protected server) * Value: `lb.example.com` (load balancer or proxy) The equivalent property setting is `com.sun.identity.agents.config.fqdn.mapping[agent.example.com]=lb.example.com`. 4. Save your work. ### Override the request protocol, host, and port In the following diagram, a load balancer or reverse proxy forwards requests and responses between clients and protected web servers. The protocol, port, and FQDN configured on the load balancer and reverse proxy are different from those on the protected web server: ![Simplified diagram showing reverse proxies and load balancers using different protocol, port, and FQDN than the web servers.](_images/LB-different.svg)Figure 3. Different protocol, port, and FQDN | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Agent configuration for TLS offloading prevents FQDN checking and mapping. Consequently, URL rewriting and redirection don't work correctly when the agent is accessed directly instead of 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 web server directly from behind the load balancer. | Use [Agent Deployment URI Prefix](../properties-reference/com.sun.identity.agents.config.agenturi.prefix.html) to override the agent protocol, host, and port with that of the load balancer or reverse proxy. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | When the following headers are defined on the proxy or load-balancer, they override the value of [Agent Deployment URI Prefix](../properties-reference/com.sun.identity.agents.config.agenturi.prefix.html):- `X-Forwarded-Proto` - `X-Forwarded-Host` - `X-Forwarded-Port`If you are using these headers, do not configure the agent to override its hostname, port, or protocol. | 1. Log in to the AM admin UI as an administrative user with rights to modify the agent profile. 2. Go to Realms > *Realm Name* > Applications > Agents > Web > *Agent Name*. 3. Set the following options in the Global tab: * Agent Deployment URI Prefix: Set to the URI of the load balancer or proxy. This value is used to override the protocol, host, and port of the protected server. The equivalent property setting is [Agent Deployment URI Prefix](../properties-reference/com.sun.identity.agents.config.agenturi.prefix.html) = `external.example.com`. * Agent Root URL for CDSSO: Set to the URL of the load balancer or proxy. The equivalent property setting is [Agent Root URL for CDSSO](../properties-reference/sunIdentityServerDeviceKeyValue.html) = `https://external.example.com:443`. 4. Enable the following options in the Advanced tab: * Override Request URL Protocol The equivalent property setting is [Enable Override Request URL Protocol](../properties-reference/com.sun.identity.agents.config.override.protocol.html) = `true`. * Override Request URL Host The equivalent property setting is [Enable Override Request URL Host](../properties-reference/com.sun.identity.agents.config.override.host.html) = `true`. * Override Request URL Port The equivalent property setting is [Enable Override Request URL Port](../properties-reference/com.sun.identity.agents.config.override.port.html) = `true`. 5. Save your work. ### Bypass load balancers to directly access agents In most load balanced deployments, `X-Forwarded-*` headers provide the protocol, port, and host of the load balancer to the agent. The agent returns a URL that points to the load balancer instead of to the agent. To access the agent directly, bypassing the load balancer, disable port, host, and protocol overrides with the property [Disable Override Request URL Port, Host, or Protocol](../properties-reference/com.sun.identity.agents.config.override.disable.hostmap.html). When you access the agent directly, authentication flows bypass the load balancer. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Configuration with disabled overrides isn't recommended. If you disable overrides, make sure that when bypassing the load balancer you meet the security requirements of your application deployment. Other access controls might be required to ensure that only authorized users have direct access to the application. | The agent disables overrides when all the following circumstances are true: * The request host header matches the key. * The load balancer uses the agent IP address instead of hostname. * `X-Forwarded-`** headers aren't defined on the proxy or load balancer. When `X-Forwarded-`** headers are defined, they override. [Disable Override Request URL Port, Host, or Protocol](../properties-reference/com.sun.identity.agents.config.override.disable.hostmap.html). In the following example, when the request host header matches `am.fr.*` the overrides for the protocol and host are disabled: ```none com.sun.identity.agents.config.override.hostmap[am.fr.*]=proto|host com.sun.identity.agents.config.override.protocol=true com.sun.identity.agents.config.override.host=true ``` ### 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 for a centralized web agent profile configured in the AM admin UI. The steps also mention the properties for web agent profiles that rely on local, file-based configurations: 1. Log in to the AM admin UI with a user that has permissions to modify the web agent profile. 2. Go to Realms > *Realm Name* > Applications > Agents > Web > *Agent Name*. 3. Set the following options in the Advanced tab: * Client IP Address Header: Configure the name of the header containing the IP address of the client. For example, `X-Forwarded-For`. The equivalent property setting is [Client IP Address Header](../properties-reference/com.sun.identity.agents.config.client.ip.header.html) = `X-Forwarded-For`. Configure this property if any of the following points are true: * AM policies are IP address-based. * The agent is configured for not-enforced IP rules. * The agent is configured take any decision based on the client's IP address. * Client Hostname Header: Configure the name of the header containing the FQDN of the client. For example, `X-Forwarded-Host`. The equivalent property setting is [Client Hostname Header](../properties-reference/com.sun.identity.agents.config.client.hostname.header.html) = `X-Forwarded-Host`. Configure this property if any of the following points are true: * AM policies are URL address-based. * The agent is configured for not-enforced URL rules. * The agent is configured take decisions based on the client's URL address. 4. Save your changes. ### Configure POST Data Preservation for load balancers or reverse proxies Use one of the following procedures to configure post data preservation for load balancers or reverse proxies. #### Map one agent profile to one agent instance when POST data preservation is enabled In this procedure, a separate agent profile must created in AM for each agent instance. For scalable deployments, where resources are dynamically created and destroyed, use [Map one agent profile to multiple agent instances when POST data preservation is enabled](#lb-POST-data-12all) instead. 1. Configure your load balancer or reverse proxy to ensure session stickiness when the cookie or URL query parameter are present. 2. Log in to the AM admin UI as a user that has permissions to modify the agent profile. 3. Go to Realms > *Realm Name* > Applications > Agents > Web > *Agent Name*. 4. Set the following options in the Advanced tab: * [POST Data Sticky Load Balancing Mode](../properties-reference/com.sun.identity.agents.config.postdata.preserve.stickysession.mode.html): * COOKIE: The agent creates a cookie for POST data preservation session stickiness. The content 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 `com.sun.identity.agents.config.postdata.preserve.stickysession.mode=COOKIE` or `com.sun.identity.agents.config.postdata.preserve.stickysession.mode=URL`. * [POST Data Sticky Load Balancing Value](../properties-reference/com.sun.identity.agents.config.postdata.preserve.stickysession.value.html): Configure a key-pair value separated by the `=` character. The agent creates the value when it evaluates [POST Data Sticky Load Balancing Mode](../properties-reference/com.sun.identity.agents.config.postdata.preserve.stickysession.mode.html). 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 `com.sun.identity.agents.config.postdata.preserve.stickysession.value=lb=myserver`. 5. Save your changes. #### Map one agent profile to multiple agent instances when POST data preservation is enabled Use this procedure for scalable deployments, where resources can be dynamically created or destroyed. For example, use it in deployments with load balancing, or environments running Kubernetes. 1. Configure your load balancer or reverse proxy to ensure session stickiness when the cookie or URL query parameter are present. 2. For each agent instance, configure post data preservation in the agent configuration file `agent.conf`. This configuration overrides the configuration in AM. In the following example, the settings in `agent.conf` configure two agents behind a load balancer to use the same agent profile, and provide uniqueness to the load balancer: * Agent 1: ```none com.sun.identity.agents.config.postdata.preserve.stickysession.mode = COOKIE com.sun.identity.agents.config.postdata.preserve.stickysession.value = EXAMPLE=Agent1 ``` * Agent 2: ```none com.sun.identity.agents.config.postdata.preserve.stickysession.mode = COOKIE com.sun.identity.agents.config.postdata.preserve.stickysession.value = EXAMPLE=Agent2 ``` For information about the values to use, refer to the following properties: * [POST Data Sticky Load Balancing Mode](../properties-reference/com.sun.identity.agents.config.postdata.preserve.stickysession.mode.html) * [POST Data Sticky Load Balancing Value](../properties-reference/com.sun.identity.agents.config.postdata.preserve.stickysession.value.html) 3. Restart the web server where the agent is installed.