Load Balancers

Load balancer configuration requirements differ depending on where you configure AM to store sessions and authentication sessions, as shown in the following table:

Load Balancing Requirements by Session Storage Location

Storage Location	Load Balancing Requirement	Comments
CTS token store	None. Session stickiness recommended for performance	Although the CTS token store is the authoritative source for CTS-based sessions and authentication sessions, AM servers cache the session or authentication session when: Authenticating a user Satisfying a session request An AM site configured to use CTS-based sessions achieves the best performance when the server that originally authenticated a user continually manages that user's session, since it does not need to retrieve it from the CTS token store. In the same way, an AM realm configured to use CTS-based authentication sessions achieves the best performance when the same server manages every request for the same authentication flow.
Client	None. Session stickiness recommended for performance	Although the user's session or authentication session resides in a JWT stored on the client which is passed to AM server along with the request, client-based sessions should be signed and/or encrypted for security reasons. Because decrypting and verifying the session on each request may be an expensive operation depending on the algorithms configured, AM caches the decrypt sequence in memory to improve performance. Therefore, an AM site configured to use client-based sessions achieves best performance when the same server manages every request for the same session or authentication session.
In AM's memory ^[a]	Session stickiness required	Deployments where AM stores authentication sessions in memory require sticky load balancing to route all requests pertaining to a particular authentication flow to the same AM server. If a request reaches a different AM server, the authentication flow will start anew.
^[a]Authentication sessions only.

For more information about AM session and authentication sessions, see Introducing Sessions.

Session storage location can be heterogeneous within the same AM deployment to suit the requirements of each of your realms. If your deployment uses a substantial number of CTS-based sessions, follow the recommendations for deployments configured for CTS-based sessions.

Configuring Site Sticky Load Balancing

Configure AM for sticky load balancing as follows:

To Configure Site Sticky Load Balancing

Navigate to Deployment > Sites.
Ensure you have a site created and that your servers are part of it. For more information, see "To Configure a Site With the First Server".
Ensure that the amlbcookie cookie has a unique value for each AM server:
1. Navigate to Deployment > Servers > Server Name > Advanced and review the value of the com.iplanet.am.lbcookie.value property. By default, the cookie value is set to the AM server ID.
  Keep the value of the amlbcookie cookie set to the AM server ID to improve server performance when using Web Agents.
  If you have replaced the value of the this property and you need to match the AM server URLs with their corresponding server IDs, query the global-config/servers endpoint. For example:
```
$ curl \
--header 'Accept: application/json' \
--header "iPlanetDirectoryPro: AQIC5...NDU1*" \
--header  "Accept-API-Version: resource=1.0, protocol=2.1" \
'https://openam.example.com:8443/openam/json/global-config/servers?_queryFilter=true'
       {
    "result": [
        {
            "_id": "01",
            "_rev": "-1541617246",
            "siteName": null,
            "url": "https://openam.example.com:8443/openam"
        }
    ],
    "resultCount": 1,
    "totalPagedResults": -1,
    "totalPagedResultsPolicy": "NONE"
}
```
  In the example above, the server ID for server https://openam.example.com:8443/openam is 01.
  Changes take effect only after you restart the AM server.
2. Restart the AM server. You can then check the cookie value by logging in to the AM console, and examining the amlbcookie cookie in your browser.
Tip
To change the name of the sticky load balancing cookie, see "Changing the Name of the Sticky Load Balancing Cookie".
Repeat the previous steps for each of the AM servers that should be part of the site.
Configure your load balancer to perform sticky load balancing based on the amlbcookie value.
In other words, the load balancer layer must keep track of which amlbcookie cookie value corresponds to which AM server.
When the load balancer receives a request, it inspects the value of the amlbcookie cookie, and then forwards the request to the corresponding AM server.

Load Balancer Offloading

When traffic to and from the load balancer is protected with HTTPS, you must terminate the SSL connection on the load balancer. Decrypting the traffic in the load balancer makes it possible to use cookie-based session stickiness.

You then either re-encrypt the traffic from the load balancer to AM, or make connections from the load balancer to AM over HTTP.

If you configure the load balancer in passthrough mode instead, session stickiness would not be possible.

Request Forwarding Caveats

Sticky load balancing based on the value of the amlbcookie cookie does not guarantee request forwarding to the corresponding AM server in all cases. For example, ForgeRock® Common REST API calls do not typically use cookies. Therefore, load balancers are not able to route these calls to the AM server on which a user's session is cached.

The AM server that does not hold the user's session in cache must locate the user's session by retrieving it from the CTS token store.

Handling HTTP Request Headers

HTTP requests can include information needed for access management, such as the client IP address used for adaptive risk-based authentication.

Configure your load balancer or proxy to pass the information to AM by using request headers. For example, the load balancer or proxy can send the client IP address by using the X-Forwarded-For HTTP request header.

Also configure AM to consume and to forward the headers as necessary. For example, to configure AM to look for the client IP address in the X-Forwarded-For request header, set the advanced configuration property com.sun.identity.authentication.client.ipAddressHeader to X-Forwarded-For under Deployment > Servers > Server Name > Advanced.

In a site configuration where one AM server can forward requests to another AM server, you can retain the header by adding it to the advanced configuration property openam.retained.http.request.headers. If X-Forwarded-For is the only additional header to retain, set openam.retained.http.request.headers to X-DSAMEVersion,X-Forwarded-For, for example.

Configure these properties under Deployment > Servers > Server Name > Advanced.

Load Balancers

Configuring Site Sticky Load Balancing

Tip

Load Balancer Offloading

Request Forwarding Caveats

Handling HTTP Request Headers