From 6ccd7367d86c9f9b3080b5adc2b2adf159deb5c9 Mon Sep 17 00:00:00 2001 From: Pedro Ruivo Date: Fri, 20 Jun 2025 14:49:29 +0100 Subject: [PATCH 1/4] Update documentation about volatile sessions Closes #40639 Signed-off-by: Pedro Ruivo --- docs/guides/server/caching.adoc | 22 ++----------------- .../impl/embedded/CacheConfigurator.java | 4 ++-- 2 files changed, 4 insertions(+), 22 deletions(-) diff --git a/docs/guides/server/caching.adoc b/docs/guides/server/caching.adoc index 04ab4535ce7c..10028c091d41 100644 --- a/docs/guides/server/caching.adoc +++ b/docs/guides/server/caching.adoc @@ -138,35 +138,17 @@ Since all the sessions in this setup are stored in-memory, there are two side ef * 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. +{project_name} automatically adjusts the number of entries that can be stored in memory, and increases the number of copies to prevent data loss. [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. Edit {project_name}'s cache config file (`conf/cache-ispn.xml`) for caches `sessions`, `clientSessions`, `offlineSessions` and `offlineClientSessions` with the following update: -+ --- -* Remove the `++` -* Change `owners` attribute of the `distributed-cache` tag to 2 or more --- -+ -An example of the resulting configuration for the `sessions` cache would look as follows. -+ -[source,xml] ----- - - - ----- -2. Disable `persistent-user-sessions` feature using the following command: +1. Disable `persistent-user-sessions` feature using the following command: + ---- bin/kc.sh start --features-disabled=persistent-user-sessions ... diff --git a/model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java b/model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java index 5188d832ecd6..311dc96ae29c 100644 --- a/model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java +++ b/model/infinispan/src/main/java/org/keycloak/spi/infinispan/impl/embedded/CacheConfigurator.java @@ -222,13 +222,13 @@ public static void configureSessionsCachesForVolatileSessions(ConfigurationBuild throw cacheNotFound(name); } if (builder.memory().maxCount() != -1) { - logger.warnf("Persistent user sessions disabled and memory limit is set. Ignoring cache limits to avoid losing sessions for cache %s.", name); + logger.infof("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 && builder.persistence().stores().stream().noneMatch(p -> p.attributes().attribute(AbstractStoreConfiguration.SHARED).get()) ) { - logger.warnf("Persistent user sessions disabled with number of owners set to default value 1 for cache %s and no shared persistence store configured. Setting num_owners=2 to avoid data loss.", name); + logger.infof("Persistent user sessions disabled with number of owners set to default value 1 for cache %s and no shared persistence store configured. Setting num_owners=2 to avoid data loss.", name); builder.clustering().hash().numOwners(2); } } From 452e3290020c57c4fa9bbad4b62aa7fb76b4da72 Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Fri, 20 Jun 2025 16:32:53 +0200 Subject: [PATCH 2/4] Updating the upgrade guide Signed-off-by: Alexander Schwartz --- .../upgrading/topics/changes/changes-26_3_0.adoc | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc index 6a2cf9dca2b6..c8d0a0dc575d 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc @@ -46,9 +46,12 @@ To enhance security, only users with the `admin` role in the `master` realm (ser === 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. +Previous versions of {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 docs also stated to update the `cache-ispn.xml` configuration file. +The current version will always use safe settings for the number of owners and maximum cache size for the affected user and client session caches, and will log only an INFO message. +With this behavior, there is no need any more to update the `cache-ispn.xml` configuration file. +If you previously used a custom `cache-ispn.xml` in order to use volatile sessions, we recommend reverting those changes and use the standard configuration file. === Email verification is now automatically set when using a OpenID Connect broker with `Trust email` is enabled and `Sync Mode` is `FORCE` From 47050831b7cc74b738a349979f6ed16c3eca076a Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Fri, 20 Jun 2025 17:57:17 +0200 Subject: [PATCH 3/4] More Cleanup Signed-off-by: Alexander Schwartz --- .../upgrading/topics/changes/changes-26_3_0.adoc | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc index c8d0a0dc575d..b8261d8e3b17 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc @@ -114,12 +114,6 @@ Previously the default *browser* flow had a *Browser - Conditional OTP* conditio Upgraded realms will not be changed. The updated flow will only be available for new realms. Take this change into consideration if you have automated the realm creation. -=== Volatile Session Cache Defaults - -If the `persistent-user-sessions` feature is disabled, i.e. volatile sessions are configured, {project_name} now prevents -`num_owners=1` being configured unless a shared persistent store is also configured. This is to prevent data loss on cache -rebalances. - == Deprecated features The following sections provide details on deprecated features. From f32c1af9dfdbc2ef4a9cddea3000d73aa1a28d40 Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Fri, 20 Jun 2025 17:58:36 +0200 Subject: [PATCH 4/4] More Cleanup Signed-off-by: Alexander Schwartz --- .../upgrading/topics/changes/changes-26_3_0.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc index b8261d8e3b17..a2834eb84f02 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc @@ -47,11 +47,11 @@ To enhance security, only users with the `admin` role in the `master` realm (ser === Problematic cache configurations ignored Previous versions of {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 docs also stated to update the `cache-ispn.xml` configuration file. +The docs also stated to update the `cache-ispn.xml` configuration file for volatile user sessions. The current version will always use safe settings for the number of owners and maximum cache size for the affected user and client session caches, and will log only an INFO message. With this behavior, there is no need any more to update the `cache-ispn.xml` configuration file. -If you previously used a custom `cache-ispn.xml` in order to use volatile sessions, we recommend reverting those changes and use the standard configuration file. +If you previously used a custom `cache-ispn.xml` in order to use volatile user sessions, we recommend reverting those changes and use the standard configuration file. === Email verification is now automatically set when using a OpenID Connect broker with `Trust email` is enabled and `Sync Mode` is `FORCE`