External-Mirrors/keycloak
2
0
Fork 0
mirror of https://github.com/keycloak/keycloak.git synced 2026-01-10 15:32:05 -03:30
Code Issues Packages Projects Releases Wiki Activity

Update documentation about volatile sessions

Browse Source 
Closes #40639

Signed-off-by: Pedro Ruivo <pruivo@redhat.com>
Signed-off-by: Alexander Schwartz <aschwart@redhat.com>
Co-authored-by: Alexander Schwartz <aschwart@redhat.com>
This commit is contained in:
Pedro Ruivo 2025-06-20 17:45:22 +01:00 committed by GitHub
parent e7b4f745ad
commit f4d5fa68c1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 9 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc
View File

@ -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 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 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`
@ -111,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.

22
docs/guides/server/caching.adoc
View File

@ -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 `+<memory max-count="..."/>+`
* 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]
----
<distributed-cache name="sessions" owners="2">
<expiration lifespan="-1"/>
</distributed-cache>
----
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 ...

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

@ -222,13 +222,13 @@ public final class CacheConfigurator {
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);
}
}