mirror of
https://github.com/keycloak/keycloak.git
synced 2025-12-21 14:30:05 -06:00
151 lines
10 KiB
Plaintext
151 lines
10 KiB
Plaintext
== 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.
|
|
|
|
=== Email verification is now automatically set when using a OpenID Connect broker with `Trust email` is enabled and `Sync Mode` is `FORCE`
|
|
|
|
Until now, the OpenID Connect broker did not support the standard `email_verified` claim available from the ID Tokens issued by
|
|
OpenID Connect Providers.
|
|
|
|
In this release, the broker was updated to respect the value from this claim to set the email verification status for the federated (local) user account.
|
|
Whenever users are federated for the first time or re-authenticating, if the `Trust email` setting is enabled and `Sync Mode` is set to `FORCE`,
|
|
the user account will be updated to (un)mark the email as verified.
|
|
|
|
In the future, we might evaluate changing this specific configuration to avoid automatic updates on the email verification
|
|
status on federated user accounts depending on the use cases and the demand from the community.
|
|
|
|
== 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.
|
|
====
|
|
|
|
=== Kubernetes cache stack has been deprecated
|
|
|
|
The `kubernetes` cache stack has been deprecated and will be removed in a future release. Users should transition to the `jdbc-ping` stack.
|
|
|
|
Consequently, the Keycloak Operator now uses the `jdbc-ping` cache stack by default.
|
|
|
|
=== Signing out from other devices now disabled by default
|
|
|
|
Previously, when a user updated their credentials, like changing their password or adding another factor like an OTP or Passkey, they had a checkbox *Sign out from other devices* which was checked by default. Since this release, {project_name} displays the checkbox *Sign out from other devices* not checked by default. This checkbox should now be intentionally enabled by the user to logout all the other related sessions associated to the same user.
|
|
|
|
=== Signing out from other devices will log out offline sessions
|
|
|
|
Related to the previous point, in previous versions, the *Sign out from other devices* checkbox 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.
|
|
|
|
=== Subgroup counts are no longer cached
|
|
|
|
When returning subgroups of a group, the count of subgroups of each subgroup of a group is no longer cached. With the
|
|
introduction of Fine-Grained Admin Permissions, the result set is filtered at the database level based on any permissions
|
|
defined to a realm so that the count will change accordingly to these permissions.
|
|
|
|
Instead of caching the count, a query will be executed every time to obtain the expected number of groups an administrator can access.
|
|
|
|
Most of the time, this change will not impact clients querying the API to fetch the subgroups of a group. However, if not the case,
|
|
a new parameter `subGroupsCount` was introduced to the following endpoints:
|
|
|
|
* `/realms/{realm}/groups/{id}/children`
|
|
* `/realms/{realm}/groups`
|
|
|
|
With this parameter, clients can decide whether the count should be returned to each individual group returned. To not break existing deployments,
|
|
this parameter defaults to `true` so that the count is returned if the parameter is not set.
|
|
|
|
=== 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.
|
|
|