From 84e5203174e1eebb6f54c6beff0af451c2e3906d Mon Sep 17 00:00:00 2001 From: Martin Kanis Date: Tue, 27 Jul 2021 15:28:46 +0200 Subject: [PATCH] KEYCLOAK-18738 Improve RootAuthenticationSession description --- .../topics/threat/auth-sessions-limit.adoc | 28 +++++++++++++++---- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/server_admin/topics/threat/auth-sessions-limit.adoc b/server_admin/topics/threat/auth-sessions-limit.adoc index 19731162ea..d41500d43a 100644 --- a/server_admin/topics/threat/auth-sessions-limit.adoc +++ b/server_admin/topics/threat/auth-sessions-limit.adoc @@ -1,14 +1,30 @@ +[[_limit-authentication-sessions]] === Limit Authentication Sessions -{project_name} creates an authentication session for each authentication request within a realm. This session is internally represented by `RootAuthenticationSession`. Each `RootAuthenticationSession` can have multiple authentication sessions for a given client. In a browser authentication flow, the browser session translates to `RootAuthenticationSession` while browser tabs translate to a collection of authentication sessions within the `RootAuthenticationSession`. +When a login page is opened for the first time in a web browser, {project_name} creates an object called authentication session that stores some useful information about the request. +Whenever a new login page is opened from a different tab in the same browser, {project_name} creates a new record called authentication sub-session that is stored within the authentication session. +Authentication requests can come from any type of clients such as the Admin CLI. In that case, a new authentication session is also created with one authentication sub-session. +Please note that authentication sessions can be created also in other ways than using a browser flow. The text below is applicable regardless of the source flow. NOTE: This section describes deployments that use the {jdgserver_name} provider for authentication sessions. - -Higher memory usage and a network overload in a cluster may occur for deployments where there are many active `RootAuthenticationSession` with a lot of authentication sessions. - -There is a possibility to mitigate the aforementioned threats. The maximum allowed number of `RootAuthenticationSession` should be addressed by limiting the request rate per time on the proxy or load balancer in front of {project_name}. The maximum number of authentication sessions per `RootAuthenticationSession` can be configured in `authenticationSessions` SPI by setting property `authSessionsLimit`. The default value is set to 300 authentication sessions per a `RootAuthenticationSession`. When this limit is reached, the oldest authentication session will be removed after a new authentication session request. -The following example shows how to limit the number of active authentication sessions per a `RootAuthenticationSession` to 100. +Authentication session is internally stored as `RootAuthenticationSessionEntity`. Each `RootAuthenticationSessionEntity` can have multiple authentication sub-sessions stored within the +`RootAuthenticationSessionEntity` as a collection of `AuthenticationSessionEntity` objects. {project_name} stores authentication sessions in a dedicated {jdgserver_name} cache. +The number of `AuthenticationSessionEntity` per `RootAuthenticationSessionEntity` contributes to the size of each cache entry. Total memory footprint of authentication session cache is determined by +the number of stored `RootAuthenticationSessionEntity` and by the number of `AuthenticationSessionEntity` within each `RootAuthenticationSessionEntity`. + +The number of maintained `RootAuthenticationSessionEntity` objects corresponds to the number of unfinished login flows from the browser. To keep the number of `RootAuthenticationSessionEntity` +under control, using an advanced firewall control to limit ingress network traffic is recommended. + + +Higher memory usage may occur for deployments where there are many active `RootAuthenticationSessionEntity` with a lot of `AuthenticationSessionEntity`. +If the load balancer does not support or is not configured for link:{installguide_stickysessions_link}[session stickiness], the load over network in a cluster can +increase significantly. The reason for this load is that each request that lands on a node that does not own the appropriate authentication session needs to retrieve +and update the authentication session record in the owner node which involves a separate network transmission for both the retrieval and the storage. + +The maximum number of `AuthenticationSessionEntity` per `RootAuthenticationSessionEntity` can be configured in `authenticationSessions` SPI by setting property `authSessionsLimit`. The default value is set to 300 `AuthenticationSessionEntity` per a `RootAuthenticationSessionEntity`. When this limit is reached, the oldest authentication sub-session will be removed after a new authentication session request. + +The following example shows how to limit the number of active `AuthenticationSessionEntity` per a `RootAuthenticationSessionEntity` to 100. [source,xml]