keycloak · ahus1 · Jul 7, 2025 · Jul 1, 2025 · Jul 2, 2025
@@ -24,20 +24,4 @@ Clients can request an offline token by adding the parameter `scope=offline_acce
 
 {project_name} will limit its internal cache for offline user and offline client sessions to 10000 entries by default, which will reduce the overall memory usage for offline sessions.
 Items which are evicted from memory will be loaded on-demand from the database when needed.
-To set different sizes for the caches, edit {project_name}'s cache config file to set a `+<memory max-count="..."/>+` for those caches.
-
-If you disabled feature `persistent-user-sessions`, it is possible to reduce memory requirements using a configuration option that shortens lifespan for imported offline sessions. Such sessions will be evicted from the Infinispan caches after the specified lifespan, but still available in the database. This will lower memory consumption, especially for deployments with a large number of offline sessions.
-
-To specify the lifespan override for offline user sessions, start {project_name} server with the following parameter:
-
-[source,bash]
-----
---spi-user-sessions--infinispan--offline-session-cache-entry-lifespan-override=<lifespan-in-seconds>
-----
-
-Similarly for offline client sessions:
-
-[source,bash]
-----
---spi-user-sessions--infinispan--offline-client-session-cache-entry-lifespan-override=<lifespan-in-seconds>
-----
+See the server configuration guide to change this default.
@@ -42,6 +42,12 @@ configured directly via {project_name}: `cache-embedded-network-bind-address`, `
 `cache-embedded-network-external-address`, `cache-embedded-network-external-port`. Configuring ports using the old
 properties will still function as before, but we recommend to change to the CLI options as this may change in the future.
 
+=== Volatile user sessions affecting offline session memory requirements
+
+Starting with this release, {project_name} will cache by default only 10000 entries for offline user and client sessions in memory when volatile user sessions are enabled. This will greatly reduce memory usage.
+
+Use the options `cache-embedded-offline-sessions-max-count` and `cache-embedded-offline-client-sessions-max-count` to change size of the offline session caches.
+
 // ------------------------ Deprecated features ------------------------ //
 == Deprecated features
 
@@ -53,6 +59,12 @@ The `displayTest` field in the `ConsentScopeRepresentation` class returned by th
 A new field `displayText` with the correct spelling has been added to replace it. The old field will be removed in {project_name} 27.0.
 The Typescript code `ConsentScopeRepresentation` for the Account Console already contains only the new field.
 
+=== Lifetime of offline session caches
+
+The options `--spi-user-sessions--infinispan--offline-session-cache-entry-lifespan-override` and `spi-user-sessions--infinispan--offline-client-session-cache-entry-lifespan-override` are now deprecated for removal.
+
+Instead use the options `cache-embedded-offline-sessions-max-count` and `cache-embedded-offline-client-sessions-max-count` to limit the memory usage if the default of 10000 cache offline user and client sessions does not work in your scenario.
+
 // ------------------------ Removed features ------------------------ //
 == Removed features
 

@@ -140,12 +140,6 @@ Since all the sessions in this setup are stored in-memory, there are two side ef
 When using volatile user sessions, the cache is the source of truth for user and client sessions.
 {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]
-====
-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. Disable `persistent-user-sessions` feature using the following command: