Disabling persistent sessions affects also offline session cache

Closes #40483

Signed-off-by: Alexander Schwartz <alexander.schwartz@gmx.net>
Signed-off-by: Alexander Schwartz <aschwart@redhat.com>

docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc

@@ -7,13 +7,13 @@ In minor or patch releases we will only do breaking changes to fix bugs.
 
 SPI options ending in `-enabled`, `-provider-default`, or `-provider` were previously treated as buildtime. However in some instances this was not correct as a provider could have a configuration property ending in one of those suffixes as well.
 
-To resolve this ambiguity, and any potential ambiguity involving SPI and provider names, a new SPI option format was introduced where the scopes and suffix are separated by `--`(double dash) instead of `-`(dash). 
+To resolve this ambiguity, and any potential ambiguity involving SPI and provider names, a new SPI option format was introduced where the scopes and suffix are separated by `--`(double dash) instead of `-`(dash).
 
 An SPI property ending in `-enabled`, `-provider-default`, or `-provider` will only be treated as buildtime if it is using the new format, e.g. `spi-<spi-name>--<provider-name>--enabled` will be recognized as a buildtime option.
 
 For instance, the correct way to reference your custom email template is: `--spi-email-template--mycustomprovider--enabled` (not `--spi-email-template-mycustomprovider-enabled`).
 
-Options using the legacy format and ending in `-enabled`, `-provider-default`, or `-provider` will instead be treated as runtime and a warning will be emitted.   
+Options using the legacy format and ending in `-enabled`, `-provider-default`, or `-provider` will instead be treated as runtime and a warning will be emitted.
 
 === Reading information about temporarily locked users
 
@@ -35,6 +35,12 @@ Notable changes where an internal behavior changed to prevent common misconfigur
 
 To enhance security, only users with the `admin` role in the `master` realm (server admins) can assign admin roles. This ensures that critical permissions cannot be delegated by realm-level administrators.
 
+=== Problematic cache configurations ignored
+
+Previous versions {project_name} warned about problematic configurations, for example, if a wrong number of owners was configured or a cache size was set when it should not have been set when enabling volatile user sessions.
+The current version will still warn about those settings, but will also ignore them to ensure a correct behavior and to avoid data loss.
+
+
 === Email verification is now automatically set when using a OpenID Connect broker with `Trust email` is enabled and `Sync Mode` is `FORCE`
 
 Until now, the OpenID Connect broker did not support the standard `email_verified` claim available from the ID Tokens issued by

docs/guides/server/caching.adoc

@@ -108,21 +108,50 @@ CPU, memory, and network utilization.
 
 These in-memory caches for user sessions and client sessions are limited to, by default, 10000 entries per node which reduces the overall memory usage of {project_name} for larger installations.
 The internal caches will run with only a single owner for each cache entry.
-Consider trade-off between memory consumption and the database utilization and set different sizes for the caches, edit {project_name}'s cache config file (`conf/cache-ispn.xml`) to set a `+<memory max-count="..."/>+` for those caches.
 
-.Volatile user sessions
+.Offline user sessions
+As an OpenID Connect Provider, the server is capable of authenticating users and issuing offline tokens. When issuing an offline token after successful authentication, the server creates an offline user session and offline client session.
 
-By default, user sessions are stored in the database and loaded on-demand to the cache.
-It is possible to configure {project_name} to store user sessions in the cache only and minimize the database utilization.
+The following caches are used to store offline sessions:
+
+* offlineSessions
+* offlineClientSessions
+
+Like the user and client sessions caches, the offline user and client session caches are limited to 10000 entries per node by default. Items which are evicted from the memory will be loaded on-demand from the database when needed.
+
+.Password brute force detection
+The `loginFailures` distributed cache is used to track data about failed login attempts.
+This cache is needed for the Brute Force Protection feature to work in a multi-node {project_name} setup.
+
+.Action tokens
+Action tokens are used for scenarios when a user needs to confirm an action asynchronously, for example in the emails sent by the forgot password flow.
+The `actionTokens` distributed cache is used to track metadata about action tokens.
+
+=== Volatile user sessions
+
+By default, regular user sessions are stored in the database and loaded on-demand to the cache.
+It is possible to configure {project_name} to store regular user sessions in the cache only and minimize calls to the database.
 
 Since all the sessions in this setup are stored in-memory, there are two side effects related to this:
 
-* Losing sessions on when all {project_name} nodes restart.
+* Losing sessions when all {project_name} nodes restart.
 * Increased memory consumption.
 
+When using volatile user sessions, the cache is the source of truth for user and client sessions.
+Therefore, it is necessary to not define an upper limit on the total number of entries that can be stored via the setting `max-count`.
+Similarly, it's crucial that we replicate each entry to two nodes to prevent data loss on node failures and rolling restarts.
+
+[WARNING]
+====
+When using volatile user sessions, the `max-count` setting for the offline session is ignored.
+
+It is not recommended to use volatile user sessions when using offline sessions extensively due to potentially high memory usage.
+For volatile sessions, the time offline sessions are cached in memory can be limited with the SPI options `spi-user-sessions--infinispan--offline-client-session-cache-entry-lifespan-override` and `spi-user-sessions--infinispan--offline-session-cache-entry-lifespan-override`.
+====
+
 Follow these steps to enable this setup:
 
-1. Since the cache is the only source of truth for user and client sessions, configure caches to not limit the number of entries and to replicate each entry to at least two nodes. To do so, edit {project_name}'s cache config file (`conf/cache-ispn.xml`) for caches `sessions` and `clientSessions` with the following update:
+1. Edit {project_name}'s cache config file (`conf/cache-ispn.xml`) for caches `sessions`, `clientSessions`, `offlineSessions` and `offlineClientSessions` with the following update:
 +
 --
 * Remove the `+<memory max-count="..."/>+`
@@ -148,27 +177,8 @@ bin/kc.sh start --features-disabled=persistent-user-sessions ...
 Disabling `persistent-user-sessions` is not possible when `multi-site` feature is enabled.
 ====
 
-.Offline user sessions
-As an OpenID Connect Provider, the server is also capable of authenticating users and issuing offline tokens. Similarly to regular user and client sessions,
-when an offline token is issued by the server upon successful authentication, the server also creates an offline user session and an offline client session.
-
-The following caches are used to store offline sessions:
-
-* offlineSessions
-* offlineClientSessions
-
-Similarly to regular user and client sessions caches, also the offline user and client session caches are limited to 10000 entries per node by default. Items which are evicted from the memory will be loaded on-demand from the database when needed.
-Consider trade-off between memory consumption and the database utilization and set different sizes for the caches, edit {project_name}'s cache config file (`conf/cache-ispn.xml`) to set a `+<memory max-count="..."/>+` for those caches.
-
-.Password brute force detection
-The `loginFailures` distributed cache is used to track data about failed login attempts.
-This cache is needed for the Brute Force Protection feature to work in a multi-node {project_name} setup.
-
-.Action tokens
-Action tokens are used for scenarios when a user needs to confirm an action asynchronously, for example in the emails sent by the forgot password flow.
-The `actionTokens` distributed cache is used to track metadata about action tokens.
-
 === Configuring cache maximum size
+
 In order to reduce memory usage, it's possible to place an upper bound on the number of entries which are stored in a given
 cache. To specify an upper bound of on a cache, you must provide the following command line argument
 `--cache-embedded-$\{CACHE_NAME}-max-count=`, with `$\{CACHE_NAME}` replaced with the name of the cache you would like to
@@ -176,16 +186,20 @@ apply the upper bound to. For example, to apply an upper-bound of `1000` to the
 `--cache-embedded-offline-sessions-max-count=1000`. An upper bound can not be defined on the following caches:
 `actionToken`, `authenticationSessions`, `loginFailures`, `work`.
 
+Setting a maximum cache size for `sessions`, `clientSessions`, `offlineSessions` and `offlineClientSessions` is not supported when volatile sessions are enabled.
+
 === Configuring caches for availability
 
 Distributed caches replicate cache entries on a subset of nodes in a cluster and assigns entries to fixed owner nodes.
 
 Each distributed cache, that is a primary source of truth of the data (`authenticationSessions`, `loginFailures` and `actionTokens`) has two owners per default, which means that two nodes have a copy of the specific cache entries.
 Non-owner nodes query the owners of a specific cache to obtain data.
+When one of the owners becomes unavailable, the data is restored from the remaining owner and rebalanced across the remaining nodes.
 When both owner nodes are offline, all data is lost.
 
-The default number of owners is enough to survive 1 node (owner) failure in a cluster setup with at least three nodes. You are free
-to change the number of owners accordingly to better fit into your availability requirements. To change the number of owners, open `conf/cache-ispn.xml` and change the value for `owners=<value>` for the distributed caches to your desired value.
+The default number of two owners is the minimum number is necessary to survive one node (owner) failure or a rolling restart in a cluster setup with at least two nodes.
+A higher number increases the availability of the data, but at the expense of slower writes as more nodes need to be updated.
+Therefore, changing the number of owners for the caches `authenticationSessions`, `loginFailures` and `actionTokens` is not recommended.
 
 === Specify your own cache configuration file
 

model/infinispan/src/main/java/org/keycloak/models/sessions/infinispan/InfinispanUserSessionProviderFactory.java

@@ -340,13 +340,13 @@ public class InfinispanUserSessionProviderFactory implements UserSessionProvider
         builder.property()
                 .name(CONFIG_OFFLINE_CLIENT_SESSION_CACHE_ENTRY_LIFESPAN_OVERRIDE)
                 .type("int")
-                .helpText("Override how long offline client sessions should be kept in memory")
+                .helpText("Override how long offline client sessions should be kept in memory in seconds")
                 .add();
 
         builder.property()
                 .name(CONFIG_OFFLINE_SESSION_CACHE_ENTRY_LIFESPAN_OVERRIDE)
                 .type("int")
-                .helpText("Override how long offline user sessions should be kept in memory")
+                .helpText("Override how long offline user sessions should be kept in memory in seconds")
                 .add();
 
         builder.property()

model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java

@@ -222,10 +222,7 @@ public final class CacheConfigurator {
                 throw cacheNotFound(name);
             }
             if (builder.memory().maxCount() != -1) {
-                logger.warnf("Persistent user sessions disabled and memory limit found in configuration for cache %s. This might be a misconfiguration! Update your Infinispan configuration to remove this message.", name);
-            }
-            if (builder.memory().maxCount() == 10000 && (name.equals(USER_SESSION_CACHE_NAME) || name.equals(CLIENT_SESSION_CACHE_NAME))) {
-                logger.warnf("Persistent user sessions disabled and memory limit is set to default value 10000. Ignoring cache limits to avoid losing sessions for cache %s.", name);
+                logger.warnf("Persistent user sessions disabled and memory limit is set. Ignoring cache limits to avoid losing sessions for cache %s.", name);
                 builder.memory().maxCount(-1);
             }
             if (builder.clustering().hash().attributes().attribute(HashConfiguration.NUM_OWNERS).get() == 1 &&