Access Management 7.2.2

Load balancing

Load balancing 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 server-side 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 server-side 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 server-side 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-side 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-side sessions achieves best performance when the same server manages every request for the same session or authentication session.

In AM’s memory (authentication sessions only)

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.

For more information about AM session and authentication sessions, see Introduction to 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 server-side sessions, follow the recommendations for deployments configured for server-side sessions.

Configure site sticky load balancing

  1. In the AM admin UI go to Deployment > Sites.

  2. Ensure you have a site created and that your servers are part of it.

    For more information, see Configure a site with the first server.

  3. Ensure that the amlbcookie cookie has a unique value for each AM server:

    • Go 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 changed the value of 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.

    • Restart the AM server. You can then check the cookie value by logging in to the AM admin UI, and examining the amlbcookie cookie in your browser.

      To change the name of the sticky load balancing cookie, see Change the sticky load balancing cookie name.

  4. Repeat the previous steps for each of the AM servers that should be part of the site.

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

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