Web Agents 2024.11

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

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.

  • 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 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, or configure Agent Profile ID Allow List.

    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 and NGINX 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.

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.

    • Context path: AM’s deployment URI. For example, /am.

    Learn more in 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 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.

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.

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.
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 = 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 = 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 = 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.
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 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:

  • 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 = 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 = https://external.example.com:443.

  4. Enable the following options in the Advanced tab:

  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.

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.

In the following example, when the request host header matches am.fr.* the overrides for the protocol and host are disabled:

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

      • 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: Configure a key-pair value separated by the = character.

      The agent creates the value when it evaluates POST Data Sticky Load Balancing Mode. 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:

      com.sun.identity.agents.config.postdata.preserve.stickysession.mode = COOKIE
com.sun.identity.agents.config.postdata.preserve.stickysession.value = EXAMPLE=Agent1

    • Agent 2:

      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:

  3. Restart the web server where the agent is installed.