keycloak/docs/documentation/upgrading/topics/changes/changes-26_4_0.adoc

// ------------------------ Breaking changes ------------------------  //
== Breaking changes

Breaking changes are identified as requiring changes from existing users to their configurations.
In minor or patch releases we will only do breaking changes to fix bugs.

=== Fine-grained admin permissions: RESET_PASSWORD scope for Users

A new `reset-password` scope has been added to the Users resource type in Fine-Grained Admin Permissions v2. This scope allows administrators to grant password reset permissions independently from the broader `manage` scope.

By default, the behavior remains compatible with previous versions through the `fallbackToManageUsers` configuration option, which is set to `true` by default. When this fallback is enabled, password reset permissions will use the existing `manage` scope behavior.

To enable the new granular password reset permissions, set the configuration option:

[source]
----
fgap.v2.resetPassword.fallbackToManageUsers=false
----

When the fallback is disabled, only explicit `reset-password` scope permissions will allow password reset operations, providing more fine-grained control over administrative access.

For more information about fine-grained admin permissions, see the link:{adminguide_finegrained_link}[{adminguide_finegrained_name}] chapter in the {adminguide_name}.

// ------------------------ Notable changes ------------------------ //
== Notable changes

Notable changes where an internal behavior changed to prevent common misconfigurations, fix bugs or simplify running {project_name}.

=== Usage of the `exact` request parameter when searching users by attributes

If you are querying users by attributes through the User API where you want to fetch users that match a specific attribute key (regardless the value),
you should consider setting the `exact` request parameter to `false` when invoking the `+/admin/realms/{realm}/users+` using
the `GET` method.

For instance, searching for all users with the attribute `myattribute` set should be done as follows:

[source]
----
GET /admin/realms/{realm}/users?exact=false&q=myattribute:
----

The {project_name} Admin Client is also updated with a new method to search users by attribute using the `exact` request parameter.

=== Automatic database connection properties for the PostgreSQL driver

When running PostgreSQL reader and writer instances, {project_name} needs to always connect to the writer instance to do its work.

Starting with this release, and when using the original PostgreSQL driver, {project_name} sets the `targetServerType` property of the PostgreSQL JDBC driver to `primary` to ensure that it always connects to a writable primary instance and never connects to a secondary reader instance in failover or switchover scenarios.

You can override this behavior by setting your own value for `targetServerType` in the DB URL or additional properties.

=== Cache configuration removed from cache-ispn.xml

The `conf/cache-ispn.xml` file no longer contains the default cache configurations.
It is still possible to overwrite the cache configurations used by {project_name} in this file, however {project_name} will log a warning if the `--cache-config-mutate=true` option is not set.
Custom caches can still be added without setting this option.

When upgrading an existing deployment, remove all default cache configurations from your existing `conf/cache-ispn.xml`
and use the `+--cache-...+` options to make changes for example to the cache sizes.

=== Operator default affinity configuration changed

The default affinity strategy has been updated so that a `preferredDuringSchedulingIgnoredDuringExecution` anti-affinity rule
is created for both zones and nodes in order to increase availability in the presence of failures. Previously the default
preferred that all nodes were deployed to the same availability zone. See the link:{highavailabilityguide_link}[{highavailabilityguide_name}]
for more details.

=== JGroups system properties replaced with CLI options

Until now it was necessary to configure JGroups network addresses and ports using the `+jgroups.bind.*+` and `+jgroups.external_*+`
system properties. In this release we have introduced the following CLI options to allow these addresses and ports to be
configured directly via {project_name}: `cache-embedded-network-bind-address`, `cache-embedded-network-bind-port`,
`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.

=== External IDP tokens automatically refreshed

When using the `+/realms/{realm-name}/broker/{provider_alias}/token+` endpoint for an OAuth 2.0 IDPs that provides refresh tokens and JSON responses or for OIDC IDPs, the tokens will be automatically refreshed each time they are retrieved via the endpoint if the access token has expired and the IDP provided a refresh token.

When using GitHub as an IDP, you can now enable JSON responses to leverage the token refresh for this endpoint.

=== Persistent User Session Batching Disabled

The batching of persistent user session updates has been turned off by default because it negatively impacts performance with some database vendors, which offset the benefits with other database vendors.
It can be enabled using the CLI option `--spi-user-sessions--infinispan--use-batches=true`, but users are encouraged to load test their environment to verify performance improvements.

== Required field in User Session note mapper

The name of the session note is now shown as a required field in the Admin UI.

== Required field in OIDC attribute mapper

The name of the token claim is now shown as a required field in the Admin UI.

=== 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.

=== Translation resource bundle file names

The naming of resource bundles in classloader and folder based themes is now aligned with Java https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/ResourceBundle.html#getBundle(java.lang.String,java.util.Locale,java.lang.ClassLoader)[ResourceBunndle#getBundle] file names.
For all included community languages like `de` or `pt-BR` a file is as before named `messages_de.properties` or `messages_pt_BR.properties`.
If you added custom language code, you should check if your file names are still the same.

The languages "Chinese (traditional)" and "Chinese (simplified)" are named for historical reasons `zh-TW` and `zh-CN` in the community themes of {project_name}.
As a start to migrate to the new language codes `zh-Hant` and `zh-Hans`, the classloader and folder based themes pick up for the old language codes `zh-TW` and `zh-CN` also the files `messages_zh_Hant.properties` and `messages_zh_Hant.properties`.
Entries in `messages_zh_Hant.properties` take precedence over entries in `messages_zh_TW.properties`, and entries in `messages_zh_Hans.properties` take precedence over entries in `messages_zh_CN.properties`.

=== Supported Update Email Feature

The `Update Email` is now a supported feature so it is no longer needed to enable the feature during the server startup.
The feature is enabled for a realm, if `Update Email` required action is enabled in the realm's required actions setting.
The feature slightly changes behaviour from previous versions when updating the profile during the authentication flow (e.g. when running the `UPDATE_PROFILE` required action).
If an existing user does have an email set when updating the profile during the authentication flow, the email attribute will not be available.

=== New database index on the `EVENT_ENTITY` table

The table `EVENT_ENTITY` now has an index `IDX_EVENT_ENTITY_USER_ID_TYPE` on the columns `USER_ID` and `TYPE` to allow a faster search in the admin UI for events of a specific user and event type.

If the table contain more than 300000 entries, {project_name} will skip the index creation by default during the automatic schema migration and instead log the SQL statement on the console during migration to be applied manually after {project_name}'s startup.
See the link:{upgradingguide_link}[{upgradingguide_name}] for details on how to configure a different limit.

=== Encryption algorithms for SAML updated

When a SAML client was enabled to *Encrypt Assertions*, the assertion included in the SAML response was encrypted following the link:https://www.w3.org/TR/xmlenc-core1/[XML Encryption Syntax and Processing] specification. The algorithms used for encryption were fixed and outdated. Since this release, default encryption options are up to date and better suited in terms of security. Besides, the encryption details are also configurable, just in case a specific client needs a different set of algorithms to work properly. New attributes can be defined in the client to specify the exact algorithms used for encryption. The Admin console displays them in the client tab *Settings*, section *Signature and Encryption*, when the *Encrypt Assertions* option is enabled in the *Keys* tab.

In order to maintain backwards compatibility, {project_name}'s upgrade will modify the existing SAML clients to set the encryption attributes to work as before. This way old clients will receive the same encrypted assertion using the same previous algorithms. If the client supports the new default configuration, removing the attributes is recommended.

For more information about client configuration, please see link:{adminguide_link}#_client-saml-configuration[Creating a SAML client] chapter in the {adminguide_name}.

=== Validate email action

When validating an email address as a required action or an application initiated action, a user can resend the verification email by default only every 30 seconds, while in earlier versions there was no limitation in re-sending the email.

Administrators can configure the interval per realm in the Verify Email required action in the Authentication section of the realmm.

=== Tracing extended for embedded Infinispan caches

When tracing is enabled, now also calls to other nodes of a {project_name} cluster will create spans in the traces.

To disable this kind of tracing, set the option `tracing-infinispan-enabled` to `false`.

=== LDAP Connection Timeout Default

If no value is specified either on the LDAP configuration as the connectionTimeout or via the `com.sun.jndi.ldap.connect.timeout` system property, the default timeout
will be 5 seconds. This will ensure that requests will see errors rather than indefinite waits in obtaining an LDAP connection from the pool or when making a connection to the LDAP server.

=== Login theme optimized for OTP and recovery code entry

The input fields  in the login theme for OTP and recovery codes and have been optimized:

* The input mode is now `numeric`, which will ease the input on mobile devices.
* The auto-complete is set to `one-time-code` to avoid interference with password managers.

=== UTF-8 management in the email sender

Since this release, {project_name} adds a new option `allowutf8` for the realm SMTP configuration (*Allow UTF-8* field inside the *Email* tab in the *Realm settings* section of the Admin Console).
For more information about email configuration, see the link:{adminguide_link}#_email[Configuring email for a realm] chapter in the {adminguide_name}.

Enabling the option encodes email addresses in UTF-8 when sending them, but it depends on the SMTP server to also supports UTF-8 via the SMTPUTF8 extension.
If *Allow UTF-8* is disabled, {project_name} will encode the domain part of the email address (second part after `@`) using punycode if non-ASCII characters are used, and will reject email addresses that use non-ASCII characters in the local part. The built-in User Profile email validator also checks that the local part of the address contains only ASCII characters when this option is disabled, avoiding the registration of emails that cannot be used by the SMTP configuration.

If you have an SMTP server configured for your realm, perform the following migration after the upgrade:

* If your SMTP server supports SMTPUTF8:
. Enable the *Allow UTF-8* option.
* If your SMTP server does not support SMTPUTF8:
. Keep the *Allow UTF-8* option disabled.
. Verify that no email addresses of users have non-ASCII characters in the local part of the email address. If you detect emails with non-ascii characters in the local part you can use the Verify Profile action to force the user to modify the email after the upgrade.

// ------------------------ Deprecated features ------------------------ //
== Deprecated features

The following sections provide details on deprecated features.

=== Deprecated `displayTest` field in `ConsentScopeRepresentation`

The `displayTest` field in the `ConsentScopeRepresentation` class returned by the Account REST service has been deprecated due to a typo in its name.
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.

=== Deprecated Passkeys Conditional UI Authenticator requires a feature

The authenticator *Passkeys Conditional UI Authenticator*, which was deprecated in the previous version 26.3.0, is still available for now, but it requires the feature
`passkeys_conditional_ui_authenticator` to be explicitly enabled during server startup. The feature itself is deprecated and disabled by default.
This allows administrator to start the server and re-configure authentication flows for passkeys authentication in a recommended way as described
in the link:{adminguide_link}#passkeys_server_administration_guide[Passkeys] chapter in the {adminguide_name}. In the future major version, we plan to remove the feature
as well as the *Passkeys Conditional UI Authenticator* as already announced.

=== Modifying default cache configurations in the cache config file

All {project_name} default cache configurations have been removed from `conf/cache-ispn.xml`.
Configuration of the default cache configurations in `conf/cache-ispn.xml`, or in a custom file via `--cache-config-file`, without specifying `--cache-config-mutate=true` is now deprecated and will log a warning.

In a future major release, the start-up will fail if default cache configurations are stated in those files and the option is not specified.


=== Welcome Page changes

The Welcome Page creates regular Admin users instead of temporary ones.

// ------------------------ Removed features ------------------------ //
== Removed features

The following features have been removed from this release.

=== <TODO>