mirror of
https://github.com/keycloak/keycloak.git
synced 2026-02-18 18:37:54 -05:00
f92c27e26d
Closes #45381 Closes #45756 Signed-off-by: Ruchika <ruchika.jha1@ibm.com> Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com> Co-authored-by: Alexander Schwartz <alexander.schwartz@ibm.com>
169 lines
12 KiB
Text
169 lines
12 KiB
Text
// ------------------------ 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.
|
|
|
|
=== JavaScript-based policies can only be deployed now if the `scripts` feature is enabled
|
|
|
|
In this version, JavaScript-based policies can only be deployed if the `scripts` feature is enabled.
|
|
|
|
Until now, JavaScript-based policies were always enabled regardless of the `scripts` feature flag. However, this behavior
|
|
was causing confusion as users expected that disabling the `scripts` feature would also disable JavaScript-based policies.
|
|
It was also not aligned with how other script-based features work in {project_name}.
|
|
|
|
If you have existing JavaScript-based policies, make sure to enable the `scripts` feature when starting {project_name}.
|
|
|
|
=== Stricter Validation for Client URIs (secure-client-uris)
|
|
The 'secure-client-uris' client policy executor has been updated to enforce stricter validation on Client URIs. This aligns with FAPI 2.0 security requirements by mandating TLS (HTTPS) for client endpoints.
|
|
|
|
HTTPS Enforcement: The following URIs must now use the https scheme. Existing clients configured with http in these fields will fail validation during updates:
|
|
'Post logout redirect URIs', 'Logo URL', 'Policy URL', and 'Terms of Service URL'.
|
|
|
|
Expanded Wildcard Support: The + wildcard character is now allowed in 'Valid post logout redirect URIs' and 'Web origins'.
|
|
Configuring + defers validation to the client's standard 'Valid redirect URIs'. Since redirect URIs are already checked for HTTPS, using the wildcard maintains FAPI 2.0 compliance while reducing configuration duplication.
|
|
|
|
Administrators must ensure that all configured URIs for the fields listed above use https. Clients attempting to update or register with http in these fields will fail validation when using the 'secure-client-uris' executor.
|
|
|
|
|
|
// ------------------------ 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}.
|
|
It also lists significant changes to internal APIs.
|
|
|
|
=== Dev Mode defaults to localhost
|
|
|
|
When running the server in dev mode on a platform other than Windows Subsystem For Linux, the `http-host` setting will default to localhost.
|
|
This ensures your dev instance won't be accessible from
|
|
other machines. If you want the previous behavior of binding to all interfaces, then explicitly set `http-host` to `0.0.0.0`.
|
|
|
|
=== Graceful shutdown of HTTP stack
|
|
|
|
Starting with this version, {project_name} will apply a shutdown delay and a shutdown timeout of one second each to allow a graceful termination.
|
|
|
|
Users should adjust those values depending on their proxy setup.
|
|
See the section https://www.keycloak.org/server/reverseproxy#graceful-http-shutdown[Graceful HTTP shutdown] in the reverse proxy guide for more information.
|
|
|
|
=== `X-Forwarded-Prefix` Header is now supported
|
|
|
|
With `proxy-headers` set to `xforwarded`, the server can determine the proxy context path from the `X-Forwarded-Prefix` header.
|
|
|
|
=== New database indexes on the `BROKER_LINK` table
|
|
|
|
The `BROKER_LINK` table now contains two additional indexes `IDX_BROKER_LINK_USER_ID` and `IDX_BROKER_LINK_IDENTITY_PROVIDER` to improve performance.
|
|
|
|
If the table contains 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.
|
|
|
|
=== Client secret authentication method
|
|
|
|
OIDC specification has multiple client authentication methods. Two of them `client_secret_basic` and `client_secret_post` are implemented in {project_name} by **Client Id and Secret**
|
|
client authenticator. Until now, when the OIDC client registration request was sent with the attribute `token_endpoint_auth_method` set to `client_secret_basic` or `client_secret_post`,
|
|
the {project_name} allowed to authenticate client with both `client_secret_basic` and `client_secret_post` methods and did not preserve the single method specified in the OIDC client
|
|
registration request. Now the specified method is respected, so for example when the OIDC client registration is sent with `token_endpoint_auth_method` set to `client_secret_post`, then
|
|
it is required to authenticate the client really with the client secret sent as a parameter in the POST request body.
|
|
|
|
It is still possible to make the OIDC client allow both methods and clients migrated from previous versions are set by default to allow authentication with both methods.
|
|
|
|
=== Zero-downtime patch releases enabled by default
|
|
|
|
Zero-downtime patch releases are now enabled by default. This feature, previously in preview as `rolling-updates:v2`, allows you to perform rolling updates when upgrading to a newer patch version within the same `major.minor` release stream without service downtime.
|
|
|
|
The `rolling-updates:v2` feature flag is no longer required.
|
|
|
|
When using the {project_name} Operator, set the update strategy to `Auto` to benefit from this functionality.
|
|
|
|
For more details on the Operator configuration, see the https://www.keycloak.org/operator/rolling-updates[Avoiding downtime with rolling updates] guide.
|
|
|
|
=== Infinispan 16 upgrade
|
|
|
|
{project_name} now uses Infinispan 16.0 for embedded distributed caching. This upgrade brings improved performance, enhanced security, and better support for zero-downtime upgrade in patch releases.
|
|
|
|
If you are using an external {jdgserver_name} server for example in a multi-cluster setup, you should upgrade to version 16.0 as this is the version {project_name} was tested with.
|
|
|
|
=== Usage of virtual threads for embedded caches
|
|
|
|
Previously virtual threads were used when at least two CPU cores were available.
|
|
Starting with this version, virtual threads are only used when at least four CPU cores are available.
|
|
This change should prevent deadlocks due to pinned virtual threads.
|
|
|
|
=== HTTP Access log does not contain specific sensitive information
|
|
|
|
Specific sensitive information is omitted from the HTTP Access log, such as the value of the `Authorization` HTTP header. Moreover, values of specific sensitive {project_name} cookies, such as `KEYCLOAK_SESSION`, `KEYCLOAK_IDENTITY`, or `AUTH_SESSION_ID`, are also omitted.
|
|
|
|
=== Rejecting URL paths with semicolons
|
|
|
|
Previously {project_name} accepted HTTP requests with paths containing a semicolon (`;`).
|
|
When processing them, it handled them according to RFC 3986 as a separator for matrix parameters, which basically ignored those parts.
|
|
As this has led to hard-to-configure URL filtering, for example, in reverse proxies, this is now disabled, and {project_name} responds with an HTTP 400 response code.
|
|
|
|
To analyze rejected requests in the server log, enable debug logging for `org.keycloak.quarkus.runtime.services.RejectNonNormalizedPathFilter`.
|
|
|
|
To revert to the previous behavior and to accept matrix parameters set the option `http-accept-non-normalized-paths` to `true`.
|
|
With this configuration, enable and review the HTTP access log to identify problematic requests.
|
|
|
|
=== Adjusted default clock-skew for not-before JWT token checks
|
|
|
|
Previous versions of {project_name} tested the issued-at timestamp with a clock-skew of zero seconds by default if this value was provided in a token.
|
|
By default, access tokens issued by {project_name} used for the admin API or for the user info endpoint do not contain a not-before claim in the token, but customized setups might have it.
|
|
In a setup with such a claim configured and with clocks that were not fully synchronized, this could lead to rejecting tokens on a node that lagged behind, as it would consider the tokens not valid yet.
|
|
|
|
Starting with this version, {project_name} will honor a clock skew of 10 seconds for the issued-at timestamp by default which is aligned with the best practices for example of the https://openid.net/specs/fapi-security-profile-2_0-final.html#section-5.3.2.1-6[FAPI 2.0 Security Profile].
|
|
|
|
This applies to all places where no explicit configuration of clock skew is configured except for JWT Client Assertions that have a hardcoded clock skew of 15 seconds.
|
|
It does not affect any explicitly configured clock skew for example in identity providers where an individual clock skew can be configured.
|
|
|
|
=== The base themes are now abstract
|
|
|
|
All the `base` themes are now tagged as **abstract**, and they are not listed in the admin console to be selected (**Realm Settings** -> **Themes** tab). They were always intended to be only extended but not used directly. If you use one of them, it will continue working (or not working) in the same way but cannot be selected using the admin console anymore. Please select one of the available default themes or create your own one.
|
|
|
|
=== New database indexes on the `OFFLINE_CLIENT_SESSION` table
|
|
|
|
The `OFFLINE_CLIENT_SESSION` table now contains two additional indexes `IDX_OFFLINE_CSS_BY_CLIENT_AND_REALM` and `IDX_OFFLINE_CSS_BY_USER_SESSION_AND_OFFLINE` to improve performance.
|
|
|
|
If the table contains 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.
|
|
|
|
=== `UserSessionProvider` API changes
|
|
|
|
The internal `UserSessionProvider` interface received new methods for efficient streaming of user sessions, in both speed and memory.
|
|
The streaming instances are read-only, meaning they will not change.
|
|
The previous methods have been deprecated.
|
|
Custom providers should implement these new methods to avoid performance penalties.
|
|
They should avoid keeping the returned items in memory by for example binding them to the current transaction, in case the invoker needs to analyze all data.
|
|
|
|
A similar change was done for the `UserSessionPersisterProvider`.
|
|
|
|
// ------------------------ Deprecated features ------------------------ //
|
|
== Deprecated features
|
|
|
|
The following sections provide details on deprecated features.
|
|
|
|
=== Deprecation of specific tracing properties in Keycloak CR
|
|
|
|
The `tracing.serviceName`, and `tracing.resourceAttributes` fields of the Keycloak CR, are now deprecated.
|
|
You should use the new `telemetry.serviceName`, and `telemetry.resourceAttributes` fields that are shared among all OpenTelemetry components - logs, metrics, and traces.
|
|
|
|
=== Deprecation of tracing span attributes for HTTP requests
|
|
|
|
The OpenTelemetry tracing span attributes `code.function` and `code.namespace` are deprecated for the HTTP request spans when tracing is enabled.
|
|
These attributes will be removed in the next major release, and only the fully qualified `code.function.name` span attribute will stay.
|
|
|
|
=== Deprecation of legacy Token Exchange
|
|
|
|
The feature link:{securing_apps_token_exchange_link}#_legacy-token-exchange[Legacy token exchange version 1 (V1)], although in preview for a very long time, is now marked as deprecated. It will never reach the supported status. Legacy Token Exchange will be removed in a future version, when its functionality can be totally or partially replaced by the supported version 2 and other features.
|
|
|
|
=== `UserSessionProvider` deprecations
|
|
|
|
The methods `getUserSessionsStream(RealmModel realm, ClientModel client)`, `getUserSessionsStream(RealmModel realm, ClientModel client, Integer firstResult, Integer maxResults)`, and `getOfflineUserSessionsStream(RealmModel realm, ClientModel client, Integer firstResult, Integer maxResults)` are deprecated for removal.
|
|
They are replaced with read-only alternatives to reduce memory consumption.
|
|
See the `UserSessionProvider` API changes section in notable changes for further information.
|
|
|
|
// ------------------------ Removed features ------------------------ //
|
|
== Removed features
|
|
|
|
The following features have been removed from this release.
|
|
|
|
=== <TODO>
|
|
|