////

== Breaking changes

Breaking changes are identified as requiring changes from existing users to their configurations.

////

== Notable changes

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

=== Upgrade procedure changed for the distribution

If you are upgrading {project_name} by downloading the distribution, the upgrade procedure has been changed. Previously it recommended copying over the contents from the `conf/` folder from the old to the new installation.
The new procedure recommends to re-apply any changes to `cache-ispn.xml` or a custom cache configuration based on the file included in the new version.

This prevents accidentally downgrading functionality, for example, by using an old `cache-ispn.xml` file from a previous version.

=== Problematic cache configurations ignored

Previous versions of {project_name} warned about problematic configurations, for example, if a wrong number of owners was configured or a cache size was set when it should not have been set when enabling volatile user sessions.
The docs also stated to update the `cache-ispn.xml` configuration file for volatile user sessions.

The current version will always use safe settings for the number of owners and maximum cache size for the affected user and client session caches, and will log only an INFO message.
With this behavior, there is no need any more to update the `cache-ispn.xml` configuration file.
If you previously used a custom `cache-ispn.xml` in order to use volatile user sessions, we recommend reverting those changes and use the standard configuration file.

=== Verify existing account by Email is only executed for the email and username sent by the identity provider

The execution *Verify Existing Account By Email* is one of the alternatives that the *First Login Flow* has to allow a brokering account to be linked to an existing {project_name} user. This step is executed when the user logs in into {project_name} through the broker for the first time, and the identity provider account is already present in {project_name}. The execution sends an email to the current {project_name} address in order to confirm the user controls that account.

Since this release, the *Verify Existing Account By Email* execution is only attempted in the *First Login Flow* if the linking attributes (email and username) sent by the external identity provider are not modified by the user during the review process. This new behavior avoids sending verification emails to an existing {project_name} account that can inadvertently accept the linking.

In case the provider needs to modify the information sent by the identity provider (because emails or usernames are different in the broker), only the other alternative *Verify Existing Account By Re-authentication* is available to link the new account to the existing {project_name} user.

If the data received from the identity provider is mandatory and cannot be modified, then the *Review Profile* step in the *First Login Flow* can be disabled to avoid any user intervention.

For more information, see link:{adminguide_link}#_identity_broker_first_login[the First login flow section of the {adminguide_name}].

=== Updates to the `user-profile-commons.ftl` theme template

The `user-profile-commons.ftl` changed to improve support for localization. See https://github.com/keycloak/keycloak/issues/38029.
As a result, and if you are extending this template, pages might start displaying a `locale` field. To avoid that, update
the theme template with the changes aforementioned.
