== Breaking changes

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

=== local admin deprecated for removal

`UrlType.LOCAL_ADMIN` and the corresponding welcome theme variable `localAdminUrl` have been deprecated for eventual removal. The default welcome resource will now simply mention localhost rather than providing a URL when an admin user has yet to be created.

=== Deprecated for removal the Instagram Identity Broker

In this release, the Instagram Identity Broker is deprecated for removal and is not enabled by default.
If you are using this broker, it is recommended to use the Facebook Identity Broker instead.

If you are using the Instagram Identity Broker and want to re-enable it, you can do it by enabling the `instagram-broker`
feature using the `features` server option:

```
--features=instagram-broker
```

It has been a while since discussions started about any activity around the Instagram Identity Broker
and any objection from the community about deprecating it for removal. For more details, see
https://github.com/keycloak/keycloak/issues/37967[Deprecate for removal the Instagram social broker].

=== Inconsistent user endpoints harmonized

In previous releases there was an inconsistency in the REST endpoint result of getting a user (`GET /admin/realms/{realm}/users/{user-id}`) and searching for a user (`GET /admin/realms/{realm}/users`). When BruteForce is enabled and a user was temporarily locked out the former endpoint would return enabled=false while the latter would return enabled=true. If the user was updated and enabled was false due to temporary lockout then the user would be disabled permanently. Both endpoints now return enabled=true when a user is temporarily locked out. To check whether a user is temporarily locked out the BruteForceUserResource endpoint should be utilised (`GET /admin/realms/{realm}/attack-detection/brute-force/users/{userId}`).

=== Deprecated password policy Recovery Codes Warning Threshold

In relation to supported Recovery codes, we deprecated the password policy `Recovery Codes Warning Threshold`. This password policy might be removed in the future major version of {project_name}.
This password policy was not related to passwords at all, but was related to recovery codes, and hence using password policy is not appropriate way for the configuration of the threshold. It is
recommended to use the configuration option *Warning Threshold* of the *Recovery Authentication Codes* required action instead of using password policy. For more details, see the link:{adminguide_link}#_recovery-codes[Recovery codes documentation].

=== Deprecated proprietary protocol for client initiated linking to the identity provider account

When you want the user, who is authenticated to your client application, to link his or her account to a specific identity provider, consider using the Application initiated action (AIA) based
mechanism with the action `idp_link`. The proprietary custom protocol for client initiated account linking is deprecated now and might be removed in the future versions. For more information, see the
Client initiated account link section of the link:{developerguide_link}[{developerguide_name}].

=== `KeycloakSessionTask.useExistingSession` method removed

`KeycloakSessionTask.useExistingSession` was only useful to private server logic. Now that this logic has been refined, there is no need for this method.

=== Deprecation of `spi-connections-infinispan-quarkus-site-name`

The option `spi-connections-infinispan-quarkus-site-name` is deprecated and no longer used for multi-site setups, and it will be removed in the future.
Use `spi-cache-embedded-default-site-name` instead in setups when running with embedded distributed caches.
See the https://www.keycloak.org/server/all-provider-config[All provider configuration] for more details on these options.

=== Removal of `jboss.site.name` and `jboss.node.name`

Both system properties have been used internally within Keycloak and have not been part of the official documentation.
{project_name} will fail to start if those are present.

Instead, use the command line option `spi-cache-embedded-default-site-name` as `jboss.site.name` replacement, and `spi-cache-embedded-default-node-name` as `jboss.node.name` replacement.
See the https://www.keycloak.org/server/all-provider-config[All provider configuration] for more details on these options.


=== Deprecation of `method RequiredActionProvider.getMaxAuthAge()`
The method `RequiredActionProvider.getMaxAuthAge()` is deprecated. It is effectively not used now. Please use the method `RequiredActionProvider.getMaxAuthAge(KeycloakSession session)` instead. This is due to enable individual configuration for required actions.

=== User searches through the User API are now respecting the user profile settings

When querying users through the User API, the user representation and their attributes are now taking into account the
user profile settings defined for the realm.

It might happen that attributes in user representations are no longer available depending on the
user profile configuration.

== Notable changes

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

=== Usage of remote stores embedded caches is restricted

The experimental feature `cache-embedded-remote-store` was removed in this release and usage of remote stores for embedded caches is now restricted.

Consider one of the following cases and recommended migration steps:

* If you are using remote stores for running {project_name} in multiple data centers especially if they do not have a direct networking connection to allow all {project_name} nodes to form a cluster, follow the link:{highavailabilityguide_link}[{highavailabilityguide_name}] for deploying a multi-site {project_name} setup.
* If you are using remote stores to keep user sessions available after a {project_name} restart, use the `peristent-user-session` feature which is enabled by default.

[WARNING]
====
* {project_name} refuses to start if the `persistent-user-session` feature is disabled and remote store is configured for any of the user session caches.

* With the feature `persistent-user-session` feature enabled, the remote store configuration is ignored and {project_name} will print a warning.
====

=== Signing out from other devices will log out offline sessions

When a user updates their credentials, like changing their password or adding another factor like an OTP or Passkey, they have a checkbox *Sign out from other devices* which is checked by default.

In previous versions, this logged out only regular sessions.
Starting with this release, it logs out also offline sessions as this is what users would expect to happen given the current screen design.

To revert to the old behavior, enable the deprecated feature `logout-all-sessions:v1`.
This deprecated feature will be removed in a future version.

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