keycloak-scim/docs/documentation/release_notes/topics/25_0_0.adoc

= Account Console v2 theme removed

The Account Console v2 theme has been removed from {project_name}. This theme was deprecated in {project_name} 24 and replaced by the Account Console v3 theme. If you are still using this theme, you should migrate to the Account Console v3 theme.

= Upgrade to PatternFly 5

In {project_name} 24, the Welcome page is updated to use https://www.patternfly.org/[PatternFly 5], the latest version of the design system that underpins the user interface of {project_name}. In this release, the  Admin Console and Account Console are also updated to use PatternFly 5. If you want to extend and customize the Admin Console and Account Console, review https://www.patternfly.org/get-started/upgrade/[the changes in PatternFly 5] and update your customizations accordingly.

= Argon2 password hashing

Argon2 is now the default password hashing algorithm used by {project_name} in a non-FIPS environment.

Argon2 was the winner of the [2015 password hashing competition](https://en.wikipedia.org/wiki/Password_Hashing_Competition)
and is the recommended hashing algorithm by [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id).

In {project_name} 24 the default hashing iterations for PBKDF2 were increased from 27.5K to 210K, resulting in a more than
10 times increase in the amount of CPU time required to generate a password hash. With Argon2 it is possible to achieve
better security, with almost the same CPU time as previous releases of {project_name}. One downside is Argon2 requires more
memory, which is a requirement to be resistant against GPU attacks. The defaults for Argon2 in {project_name} requires 7MB
per-hashing request.
To prevent excessive memory and CPU usage, the parallel computation of hashes by Argon2 is by default limited to the number of cores available to the JVM.
To support the memory intensive nature of Argon2, we have updated the default GC from ParallelGC to G1GC for a better heap utilization.

= New Hostname options

In response to the complexity and lack of intuitiveness experienced with previous hostname configuration settings, we are proud to introduce Hostname v2 options.

We have listened to your feedback, tackled the tricky issues, and created a smoother experience for managing hostname configuration.
Be aware that even the behavior behind these options has changed and requires your attention - if you are dealing with custom hostname settings.

Hostname v2 options are supported by default, as the old hostname options are deprecated and will be removed in the following releases.
You should migrate to them as soon as possible.

New options are activated by default, so {project_name} will not recognize the old ones.

For information on how to migrate, see the link:{upgradingguide_link}[{upgradingguide_name}].

= Persistent user sessions

Previous versions of {project_name} stored only offline user and offline client sessions in the databases.
The new feature `persistent-user-session` stores online user sessions and online client sessions not only in memory, but also in the database.
This will allow a user to stay logged in even if all instances of {project_name} are restarted or upgraded.

The feature is a preview feature and disabled by default. To use it, add the following to your build command:

----
bin/kc.sh build --features=persistent-user-session ...
----

For more details see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}.
The https://www.keycloak.org/high-availability/concepts-memory-and-cpu-sizing[sizing guide] contains a new paragraph describing the updated resource requirements when this feature is enabled.

NOTE: If this feature is enabled for an existing deployment that is using only the embedded Infinispan for storing sessions, the sessions will not be migrated to the database.

With persistent sessions enabled, the in-memory caches for online user sessions, offline user sessions, online client sessions and offline client sessions are limited to 10000 entries by default which will reduce the overall memory usage of Keycloak for larger installations.
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.
Once this feature is enabled, expect an increased database utilization on each login, logout and refresh token request.

To configure the cache size in an external {jdgserver_name} in a {project_name} multi-site setup, for those caches, consult the updated https://www.keycloak.org/high-availability/deploy-infinispan-kubernetes-crossdc[Deploy Infinispan for HA with the Infinispan Operator] {section}.

With this feature enabled, 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 no longer available which were used to override the time offline sessions are kept in memory.

To log out all online users sessions of a realm with the `persistent-user-session` feature enabled, use the following steps as before:

. Login to the Admin Console.
. Select the menu entry *Sessions*.
. Select the action *Sign out all active sessions*.

= Cookies updates

== SameSite attribute set for all cookies

The following cookies did not use to set the `SameSite` attribute, which in recent browser versions results in them
defaulting to `SameSite=Lax`:

* `KC_STATE_CHECKER` now sets `SameSite=Strict`
* `KC_RESTART` now sets `SameSite=None`
* `KEYCLOAK_LOCALE` now sets `SameSite=None`
* `KEYCLOAK_REMEMBER_ME` now sets `SameSite=None`

The default value `SameSite=Lax` causes issues with POST based bindings, mostly applicable to SAML, but also used in
some OpenID Connect / OAuth 2.0 flows.

== Removing KC_AUTH_STATE cookie

The cookie `KC_AUTH_STATE` is removed and it is no longer set by the {project_name} server as this server no longer needs this cookie.

= Deprecated cookie methods removed

The following methods for setting custom cookies have been removed:

* `LocaleSelectorProvider.KEYCLOAK_LOCALE` - replaced by `CookieType.LOCALE`
* `HttpCookie` - replaced by `NewCookie.Builder`
* `HttpResponse.setCookieIfAbsent(HttpCookie cookie)` - replaced by `HttpResponse.setCookieIfAbsent(NewCookie cookie)`

= Addressed 'You are already logged in' for expired authentication sessions

The Keycloak 23 release provided improvements for when a user is authenticated in parallel in multiple browser tabs. However, this improvement did not address the case when an authentication session
expired. Now for the case when user is already logged-in in one browser tab and an authentication session expired in other browser tabs, {project_name} is able to redirect back to the client
application with an OIDC/SAML error, so the client application can immediately retry authentication, which should usually automatically log in the application because of the SSO session. For more
details, see link:{adminguide_link}#_authentication-sessions[{adminguide_name} authentication sessions].

= Lightweight access token to be even more lightweight

In previous releases, the support for lightweight access token was added. In this release, we managed to remove even more built-in claims from the lightweight access token. The claims are added
by protocol mappers. Some of them affect even the regular access tokens or ID tokens as they were not strictly required by the OIDC specification.

* Claims `sub` and `auth_time` are added by protocol mappers now, which are configured by default on the new client scope `basic`, which is added automatically to all the clients. The claims are still added to the ID token and access token as before, but not to lightweight access token.
* Claim `nonce` is added only to the ID token now.  It is not added to a regular access token or lightweight access token. For backwards compatibility, you can add this claim to an access token by protocol mapper, which needs to be explicitly configured.
* Claim `session_state` is not added to any token now. It is still possible to add it by protocol mapper if needed. There is still the other dedicated claim `sid` supported by the specification, which was available in previous versions as well and which has exactly the same value.

For more details, see the link:{upgradingguide_link}[{upgradingguide_name}]..

= Password policy for check if password contains Username

Keycloak supports a new password policy that allows you to deny user passwords which contains the user username.

= Searching by user attribute no longer case insensitive

When searching for users by user attribute, {project_name} no longer searches for user attribute names forcing lower case comparisons. The goal of this change was to speed up searches by using {project_name}'s native index on the user attribute table. If your database collation is case-insensitive, your search results will stay the same. If your database collation is case-sensitive, you might see less search results than before.

= Breaking fix in authorization client library

For users of the `keycloak-authz-client` library, calling `AuthorizationResource.getPermissions(...)` now correctly returns a `List<Permission>`.

Previously, it would return a `List<Map>` at runtime, even though the method declaration advertised `List<Permission>`.

This fix will break code that relied on casting the List or its contents to `List<Map>`. If you have used this method in any capacity, you are likely to have done this and be affected.

= IDs are no longer set when exporting authorization settings for a client

When exporting the authorization settings for a client, the IDs for resources, scopes, and policies are no longer set. As a
result, you can now import the settings from a client to another client.

= Management port for metrics and health endpoints

Metrics and health checks endpoints are no longer accessible through the standard {project_name} server port.
As these endpoints should be hidden from the outside world, they can be accessed on a separate default management port `9000`.

It allows to not expose it to the users as standard Keycloak endpoints in Kubernetes environments.
The new management interface provides a new set of options and is fully configurable.

{project_name} Operator assumes the management interface is turned on by default.
For more details, see https://www.keycloak.org/server/management-interface[Configuring the Management Interface].

= Syslog for remote logging

{project_name} now supports https://en.wikipedia.org/wiki/Syslog[Syslog] protocol for remote logging.
It utilizes the protocol defined in https://datatracker.ietf.org/doc/html/rfc5424[RFC 5424].
By default, the syslog handler is disabled, but when enabled, it sends all log events to a remote syslog server.

For more information, see the https://www.keycloak.org/server/logging[Configuring logging] guide.

= Change to class `EnvironmentDependentProviderFactory`

The method `EnvironmentDependentProviderFactory.isSupported()` was deprecated for several releases and has now been removed.

For more details, see the link:{upgradingguide_link}[{upgradingguide_name}].

= All `cache` options are runtime

It is now possible to specify the `cache`, `cache-stack`, and `cache-config-file` options during runtime.
This eliminates the need to execute the build phase and rebuild your image due to them.

For more details, see the link:{upgradingguide_link}[{upgradingguide_name}].

= Removing deprecated methods from `AccessToken`, `IDToken`, and `JsonWebToken` classes

In this release, we are finally removing deprecated methods from the following classes:

* `AccessToken`
* `IDToken`
* `JsonWebToken`

For more details, see the link:{upgradingguide_link}[{upgradingguide_name}].

= Method `getExp` added to `SingleUseObjectKeyModel`

As a consequence of the removal of deprecated methods from `AccessToken`, `IDToken`, and `JsonWebToken`,
the `SingleUseObjectKeyModel` also changed to keep consistency with the method names related to expiration values.

For more details, see the link:{upgradingguide_link}[{upgradingguide_name}].