libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

Document it is not possible to use rolling configuration upgrade for enabling persistent sessions

Browse source 
Closes #29561

Signed-off-by: Michal Hajas <mhajas@redhat.com>
Signed-off-by: Alexander Schwartz <aschwart@redhat.com>
Co-authored-by: Alexander Schwartz <aschwart@redhat.com>
This commit is contained in:
Michal Hajas 2024-05-29 10:19:20 +02:00 committed by GitHub
parent 4edb204777
commit 61d0d56720
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 15 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc
View file

@ -118,7 +118,9 @@ Migrating in-memory sessions for {project_name} 24 is not supported as all {proj
==== ====
The migration of user sessions only works when the persistent user sessions is enabled when upgrading to {project_name} 25. The migration of user sessions only works when the persistent user sessions is enabled when upgrading to {project_name} 25.
If you chose to upgrade to 25 without enabling persistent user sessions, there is currently no possibility to trigger the migration of existing sessions at a later point in time. If you chose to upgrade to 25 without enabling persistent user sessions, there is currently no possibility to trigger the migration of existing sessions at a later point in time.
When you enable it later, only newly created user sessions will be persisted.
Enabling this feature later, by a configuration change, can result in an undefined behavior of {project_name} related to sessions if both persisted and non-persisted sessions co-exist. To prevent that, remove all existing online user and client sessions before the first node is started with the feature enabled.
This means all {project_name} nodes need to be stopped and, if used, {jdgserver_name} remote cache store and embedded Infinispan JDBC persistence need to be cleared.
==== ====
To migrate the user sessions during an upgrade of {project_name}, perform the following steps: To migrate the user sessions during an upgrade of {project_name}, perform the following steps:
@ -218,10 +220,10 @@ bin/kc.[sh|bat] --spi-connections-http-client-default-max-consumed-response-size
= Hostname Verification Policy = Hostname Verification Policy
The default for `spi-truststore-file-hostname-verification-policy` and the new `tls-hostname-verifier` option is now DEFAULT, rather than WILDCARD. The WILDCARD and STRICT option values have been deprecated - you should simply rely upon DEFAULT instead. The default for `spi-truststore-file-hostname-verification-policy` and the new `tls-hostname-verifier` option is now DEFAULT, rather than WILDCARD. The WILDCARD and STRICT option values have been deprecated - you should simply rely upon DEFAULT instead.
Behavior supported by WILDCARD, that is not supported by DEFAULT: Behavior supported by WILDCARD, that is not supported by DEFAULT:
* allows wildcards in subdomain names (e.g. *.foo.com) to match anything, including multiple levels (e.g. a.b.foo.com). * allows wildcards in subdomain names (e.g. *.foo.com) to match anything, including multiple levels (e.g. a.b.foo.com).
* allows matching against well known public suffixes - e.g. foo.co.gl may match *.co.gl * allows matching against well known public suffixes - e.g. foo.co.gl may match *.co.gl
Behavior supported by STRICT, that is not supported by DEFAULT: Behavior supported by STRICT, that is not supported by DEFAULT:

14
docs/guides/server/caching.adoc
View file

@ -90,7 +90,6 @@ to the node where their sessions were initially created. By doing that, you are
CPU, memory, and network utilization. CPU, memory, and network utilization.
.User sessions .User sessions
Once the user is authenticated, a user session is created. The user session tracks your active users and their state so that they can seamlessly Once the user is authenticated, a user session is created. The user session tracks your active users and their state so that they can seamlessly
authenticate to any application without being asked for their credentials again. For each application, the user authenticates with a client session authenticate to any application without being asked for their credentials again. For each application, the user authenticates with a client session
is created too, so that the server can track the applications the user is authenticated with and their state on a per-application basis. is created too, so that the server can track the applications the user is authenticated with and their state on a per-application basis.
@ -109,6 +108,7 @@ CPU, memory, and network utilization.
ifeval::[{project_community}==true] ifeval::[{project_community}==true]
.Persistent user sessions
The feature `persistent-user-session` stores online user and client sessions also in the database. The feature `persistent-user-session` stores online user and client sessions also in the database.
This will allow a user to stay logged in even if all instances of {project_name} are restarted or upgraded. This will allow a user to stay logged in even if all instances of {project_name} are restarted or upgraded.
@ -118,15 +118,21 @@ The feature is disabled by default. To use it, enable the feature:
bin/kc.sh start --features=persistent-user-session ... bin/kc.sh start --features=persistent-user-session ...
---- ----
With this feature enabled, the in-memory caches for online user sessions and online client sessions are limited to by default 10000 entries per node which will reduce the overall memory usage of {project_name} for larger installations. With this feature enabled, the in-memory caches for online user sessions and online client sessions are limited to, by default, 10000 entries per node which will reduce the overall memory usage of {project_name} for larger installations.
The internal caches will run with only a single owner for each cache entry. The internal caches will run with only a single owner for each cache entry.
Items which are evicted from memory will be loaded on-demand from the database when needed. 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. To set different sizes for the caches, edit {project_name}'s cache config file to set a `+<memory max-count="..."/>+` for those caches.
This feature can be enabled via a rolling configuration upgrade.
After the change, all new online user and client sessions are written to the database. [WARNING]
====
Enabling this feature via a rolling configuration upgrade can result in an undefined behavior of {project_name} related to sessions if both persisted and non-persisted sessions co-exist.
To prevent that, remove all online user and client sessions before the first node is started with this feature enabled.
This means all {project_name} nodes need to be stopped and, if used, {jdgserver_name} remote cache store and embedded Infinispan JDBC persistence need to be cleared.
====
endif::[] endif::[]
.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, 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. However, due to the nature 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. However, due to the nature
of offline tokens, offline sessions are handled differently as they are long-lived and should survive a complete cluster shutdown. Because of that, they are also persisted to the database. of offline tokens, offline sessions are handled differently as they are long-lived and should survive a complete cluster shutdown. Because of that, they are also persisted to the database.