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

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

Breaking changes are identified as those that might require changes for existing users to their configurations or applications.
In minor or patch releases, {project_name} will only introduce 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 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 the explicit `reset-password` scope permissions allows password reset operations, providing more fine-grained control over administrative access.

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

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

Notable changes may include internal behavior changes that prevent common misconfigurations, bugs that are fixed, or changes to 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),
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.

=== MySQL and MariaDB wait_timeout validation

In order to prevent connections being closed unexpectedly by the database server, it is necessary to ensure that the {project_name}
connection pool is correctly configured with respect to the server's `wait_timeout` setting.

Starting with this release, {project_name} defines a default `db-pool-max-lifetime` of 7 hours and 50 minutes for MySQL
and MariaDB databases as the default `wait_timeout` is 8 hours.

If the server defines a `wait_timeout` which is greater than the default, or provided, `db-pool-max-lifetime` value, then
a warning will be logged on {project_name} startup.

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

The `conf/cache-ispn.xml` file no longer contains the default cache configurations.
You can still overwrite the cache configurations used by {project_name} in this file, however {project_name} logs a warning if the `--cache-config-mutate=true` option is not set.
You can still add custom caches 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.

=== RFC8414 compliant lookup of metadata

{project_name} now exposes an RFC8414-compliant endpoint at the root URL level `/.well-known/` to allow clients to discover OAuth 2.0 Authorization Server Metadata and other well-known providers by the issuer URL.

As an example, OAuth 2.0 Authorization Server Metadata information was exposed by this URL:

[source]
----
https://keycloak.example.com/realms/{realm}/.well-known/oauth-authorization-server
----

It is now available also by this URL:

[source]
----
https://keycloak.example.com/.well-known/oauth-authorization-server/realms/{realm}
----

To benefit from this, expose the path `/.well-known/` in your reverse proxy configuration.

NOTE: If a `http-relative-path` is configured, configure a reverse proxy to map the `/.well-known/` path to the path with the prefix on the server.

=== Operator default affinity configuration changed

The default scheduling strategy has been updated so that a topology spread constraint
is created for both zones and nodes in order to increase availability in the presence of failures. Previously, the default strategy
preferred that all nodes were deployed to the same availability zone. For more details, see the link:{highavailabilityguide_link}[{highavailabilityguide_name}].

=== JGroups system properties replaced with CLI options

Previously, configuring JGroups network addresses and ports required that you use the `+jgroups.bind.*+` and `+jgroups.external_*+`
system properties. This release introduces the following CLI options to allow these addresses and ports to be
configured directly by {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 has not changed, but using the CLI options is recommended because the previous method could be deprecated.

=== External IDP tokens automatically refreshed

When using the `+/realms/{realm-name}/broker/{provider_alias}/token+` endpoint for an OAuth 2.0 IDP 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 offsets the benefits with other database vendors.
You can enable batching by 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 Console.

=== Required field in OIDC attribute mapper

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

=== Volatile user sessions affecting offline session memory requirements

Starting with this release, {project_name} caches by default only 10,000 entries for offline user and client sessions in memory when volatile user sessions are enabled. This change greatly reduces memory usage.

To change the size of the offline session caches, use the `cache-embedded-offline-sessions-max-count` and `cache-embedded-offline-client-sessions-max-count` options.

=== 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, such as `de` or `pt-BR`, a file is still named `messages_de.properties` or `messages_pt_BR.properties`.
If you added custom language code, check if your file names are still the same.

The "Chinese (traditional)" and "Chinese (simplified)" languages 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` and also the `messages_zh_Hant.properties` and `messages_zh_Hant.properties` files.
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`.

=== Update Email Feature is now supported

`Update Email` is now a supported feature so it is now enabled during the server startup.
The feature is enabled for a realm if the `Update Email` required action is enabled in the realm.
The feature slightly changes behavior from previous versions when updating the profile during the authentication flow (such as when running the `UPDATE_PROFILE` required action).
If a user has an email set when updating the profile during the authentication flow, the email attribute is not available.

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

The `EVENT_ENTITY` table now has an index `IDX_EVENT_ENTITY_USER_ID_TYPE` on the columns `USER_ID` and `TYPE`, which allows a faster search in the Admin Console for events of a specific user and event type.

If the table contains more than 300,000 entries, {project_name} skips the index creation during the automatic schema migration. However, the SQL statement appears on the console during migration so you can apply it manually after {project_name} startup.
For details on configuring a different limit, see link:{upgradingguide_link}#_migrate_db[Migrating the database].

=== 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. Starting with this release, default encryption options are up to date and better suited in terms of security. In addition, if a specific client needs a different algorithm, you can configure the encryption details. You define new attributes in the client to specify the exact algorithms used for encryption. In the Admin Console, when *Encrypt Assertions* is enabled in the *Keys* tab, these attributes appear in the client *Settings* tab, *Signature and Encryption* section.

To maintain backwards compatibility, the {project_name} upgrade modifies the existing SAML clients to set the encryption attributes to work as before. As a result, existing clients 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, see link:{adminguide_link}#_client-saml-configuration[Creating a SAML client].

=== 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 no limitation existed for re-sending the email.

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

=== Tracing extended for embedded Infinispan caches

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

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

=== LDAP Connection default timeout

If no value is specified either on the LDAP configuration as the connectionTimeout or by the `com.sun.jndi.ldap.connect.timeout` system property, the default timeout is 5 seconds. This timeout ensures 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.

=== Maximum length of the parameters in the OIDC authentication request

When the OIDC authentication request (or OAuth2 authorization request) is sent, a new limit exists for the maximum length of every standard OIDC/OAuth2 parameter. The maximum length of each standard parameter is 4,000 characters,
which is a very large number that may be lowered in a future release. For now, it remains large for backwards compatibility. The only exception is the `login_hint` parameter, which has maximum length of 255 characters. This value is aligned with the maximum length for the `username` and `email` attributes configured in the default user profile configuration.

If you want to increase or lower those numbers, start the server with the option `req-params-default-max-size` for the default maximum length of the standard
OIDC/OAuth2 parameters or you can use something such as `req-params-max-size` for one specific parameter. For more details, see the `login-protocol` provider configuration in the link:{allproviderconfigguide_link}[{allproviderconfigguide_name}].

=== UTF-8 management in the email sender

Starting with  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 link:{adminguide_link}#_email[Configuring email for a realm].

Enabling the option encodes email addresses in UTF-8 when sending them, but it depends on the SMTP server to also support UTF-8 by 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.

=== Aligning the count of users with the actual number of users returned from searches

When searching for users in the Admin Console or by the User API, the count of users returned from the
`/admin/realms/{realm}/users/count` endpoint is now aligned with the actual number of users returned when executing
searches by `/admin/realms/{realm}/users`.

If you are relying on the users count endpoint, make sure to review your clients so that they expect the users count
to be aligned with the actual number of users returned from searches.

=== Welcome Page changes

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

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

The following sections provide details on deprecated features.

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

As an alternative, use the `cache-embedded-offline-sessions-max-count` and `cache-embedded-offline-client-sessions-max-count` options to limit the memory usage if the default of 10,000 cache offline user and client sessions does not work in your scenario.

=== Passkeys Conditional UI Authenticator requires a feature

The *Passkeys Conditional UI Authenticator* authenticator was deprecated in the version 26.3.0, but you can still use it if you enable
`passkeys_conditional_ui_authenticator` during server startup. As a result, you can re-configure authentication flows for passkeys authentication as described in link:{adminguide_link}#passkeys_server_administration_guide[Passkeys]. Nonetheless, both this startup option and the *Passkeys Conditional UI Authenticator* are deprecated.

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

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

The following features have been removed from this release.

=== <TODO>