Update proxy guide with information about session stickness

Closes #16892

docs/guides/src/main/server/reverseproxy.adoc

@@ -56,6 +56,42 @@ By default, Keycloak needs to know under which hostname it will be called. If yo
 
 <@kc.start parameters="--proxy <mode> --hostname-strict=false"/>
 
+== Enable sticky sessions
+
+Typical cluster deployment consists of the load balancer (reverse proxy) and 2 or more Keycloak servers on private network.
+For performance purposes, it may be useful if load balancer forwards all requests related to particular browser session to the same Keycloak backend node.
+
+The reason is, that Keycloak is using Infinispan distributed cache under the covers for save data related to current authentication session and user session.
+The Infinispan distributed caches are configured with two owners by default. That means that particular session is primarily stored on two cluster nodes and the other nodes need to lookup the session remotely if they want to access it.
+
+For example if authentication session with ID 123 is saved in the Infinispan cache on node1, and then node2 needs to lookup this session, it needs to send the request to node1 over the network to return the particular session entity.
+
+It is beneficial if particular session entity is always available locally, which can be done with the help of sticky sessions. The workflow in the cluster environment with the public frontend load balancer and two backend Keycloak nodes can be like this:
+
+* User sends initial request to see the Keycloak login screen
+
+* This request is served by the frontend load balancer, which forwards it to some random node (eg. node1). Strictly said, the node doesn’t need to be random, but can be chosen according to some other criterias (client IP address etc). It all depends on the implementation and configuration of underlying load balancer (reverse proxy).
+
+* Keycloak creates authentication session with random ID (eg. 123) and saves it to the Infinispan cache.
+
+* Infinispan distributed cache assigns the primary owner of the session based on the hash of session ID. See Infinispan documentation for more details around this. Let’s assume that Infinispan assigned node2 to be the owner of this session.
+
+* Keycloak creates the cookie AUTH_SESSION_ID with the format like <session-id>.<owner-node-id> . In our example case, it will be 123.node2 .
+
+* Response is returned to the user with the Keycloak login screen and the AUTH_SESSION_ID cookie in the browser
+
+From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID 123 and hence Infinispan can lookup this session locally. After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID 123 .
+
+The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to sticky over the AUTH_SESSION_ID cookie. How exactly do this is dependent on your loadbalancer.
+
+If your proxy supports session affinity without processing cookies from backend nodes, you should set the `spi-sticky-session-encoder-infinispan-should-attach-route` option
+to `false` in order to avoid attaching the node to cookies and just rely on the reverse proxy capabilities.
+
+<@kc.start parameters="--spi-sticky-session-encoder-infinispan-should-attach-route=false"/>
+
+By default, the `spi-sticky-session-encoder-infinispan-should-attach-route` option value is `true` so that the node name is attached to
+cookies to indicate to the reverse proxy the node that subsequent requests should be sent to.
+
 === Exposing the administration console
 
 By default, the administration console URLs are created solely based on the requests to resolve the proper scheme, host name, and port. For instance,