keycloak · ahus1 · Dec 8, 2025 · Dec 5, 2025 · Dec 5, 2025
@@ -1,7 +1,92 @@
 // Release notes should contain only headline-worthy new features,
 // assuming that people who migrate will read the upgrading guide anyway.
 
-= Preview of enhanced HTTP performance
+////
+
+// TODO
+This release features new capabilities focused on ... The highlights of this release are:
+
+// TODO
+// ...
+
+Read on to learn more about each new feature. If you are upgrading from a previous release, https://www.keycloak.org/docs/latest/upgrading/index.html[review also the changes listed in the upgrading guide].
+
+////
+
+= Security and Standards
+
+== Logout confirmation page
+
+The client logout configuration now includes an option to show a logout confirmation page. When enabled, users will see a "`You are logged out`" confirmation page upon successful logout.
+
+== CORS enhancements
+// https://github.com/keycloak/keycloak/pull/43767
+// https://github.com/keycloak/keycloak/issues/8863
+
+For the OpenID Connect Dynamic Client Registration, you can now specify which CORS headers are allowed via the client registration access policies.
+
+For the overall CORS configuration, you can now allow environment specific headers to be allowed using the SPI option `+spi-cors--default--allowed-headers+`.
+
+== Hiding OpenID Connect scopes from the discovery endpoint
+// https://github.com/keycloak/keycloak/issues/10388
+
+Previously, all scopes of an OpenID Connect client were advertised in the discovery endpoint.
+
+In some situation you might want to avoid it, as the calling client, for example, an MCP server might not support it, or you might want to hide some scopes for preventing their discovery via public APIs.
+
+You can now prevent this by disabling *Include in OpenID Provider Metadata*.
+
+= Administration
+
+////
+// TODO
+= Federated client authentication (preview)
+////
+
+== Organization invitation management
+
+Organization administrators can now manage organization invitations through both the Admin Console and REST API:
+
+* View all sent invitations with their current status (Pending, Expired)
+* Resend pending invitations to recipients
+* Delete invitation records from the system
+* Filter invitations by status for easier management
+
+All invitations are now persistently stored in the database, providing better tracking and management capabilities.
+
+The invitation management features are available in the *Invitations* tab when managing an organization in the Admin Console, and through the Organizations REST API endpoints under `+/admin/realms/{realm}/orgs/{orgId}/invitations+`.
+
+== New event `USER_SESSION_DELETED`
+
+For each expired user session there is a new user event `USER_SESSION_DELETED` fired.
+This event is published approximately 3-10 minutes after the session has expired depending on job scheduling and load on the system.
+By default, this event is not persisted.
+
+As part of this change, the process now deletes rows from the table in small batches, instead of issuing a delete statements that affects the whole table.
+This should allow for better response times when there are a lot of sessions in the table.
+
+= Configuring and Running
+
+== Containers for PowerPC 64-bit Little Endian architecture
+
+The containers for both the {project_name} and its operator are not available as well for the PowerPC 64-bit Little Endian (ppc64le) architecture. This is in addition to the existing amd64 and arm64.
+
+We expect this to allow users to optimize their usage of open hardware and power consumption.
+
+== Session cache affinity
+
+Authentication, user, and client sessions are now created on the respective {project_name} node and avoid extra remote calls to neighbors when reading or writing them to the embedded caches.
+
+When you have sticky sessions enabled in your loadbalancer, you will benefit from this feature automatically, and you should see reduced response times when authenticating users.
+
+== PostgreSQL version updates
+
+The latest major release of PostgreSQL 18 is now supported.
+As PostgreSQL 13 is end-of-life it is now longer supported.
+
+We also updated the docs on how to use a TLS certificate for the JDBC-connection when connecting to a PostgreSQL database.
+
+== Enhanced HTTP performance (preview)
 
 You can now enable a more efficient way to handle JSON data in the HTTP layer.
 This change increases throughput by ~5%, stabilizes response times, and reduces system resource usage.
@@ -15,13 +100,19 @@ endif::[]
 
 For more details, see the https://www.keycloak.org/server/configuration-production[Configuring Keycloak for production] guide.
 
-= Breaking Fix for Windows in Loopback Hostname Verification
+== Enable/disable features via a single option
 
-This release introduces a breaking change for Windows users: setups that previously relied on custom machine names or non-standard hostnames for loopback (e.g., `127.0.0.1` resolving to a custom name) may require updates to their trusted domain configuration. Only `localhost` and `*.localhost` are now recognized for loopback verification.
+You can now enable or disable individual features using the `feature-<name>` option (like `feature-spiffe=enabled`).
 
-Keycloak now consistently normalizes loopback addresses to `localhost` for domain verification across all platforms. This change ensures predictable behavior for trusted domain checks, regardless of the underlying OS.
+This provides a more fine-grained way to manage features and eliminates the need to maintain long lists of enabled or disabled features.
 
-= Export traces with custom request headers
+The `feature-<name>` option takes precedence over both `features` and `features-disabled`.
+
+For more details, see the https://www.keycloak.org/server/features[Enabling and disabling features] guide.
+
+= Observability
+
+== Export traces with custom request headers
 
 It is now possible to set request headers for exporting traces via Open Telemetry Protocol (OTLP).
 It is mainly useful for providing tokens in the request.
@@ -30,16 +121,6 @@ You can specify these headers via the `tracing-header-<header>` wildcard option,
 
 For more details, see the  link:{tracingguide_link}[{tracingguide_name}] guide.
 
-= Enable/disable features via a single option
-
-You can now enable or disable individual features using the `feature-<name>` option (like `feature-spiffe=enabled`).
-
-This provides a more fine-grained way to manage features and eliminates the need to maintain long lists of enabled or disabled features.
-
-The `feature-<name>` option takes precedence over both `features` and `features-disabled`.
-
-For more details, see the https://www.keycloak.org/server/features[Enabling and disabling features] guide.
-
 == MDC Logging feature (supported)
 
 The `log-mdc:v1` feature has been promoted from a preview feature to a supported feature.
@@ -48,19 +129,3 @@ MDC enables Keycloak to enrich log entries with contextual information such as r
 
 For more details, see the https://www.keycloak.org/server/logging#_adding_context_for_log_messages[Adding context for log messages] guide.
 
-= Organization invitation management
-
-Organization administrators can now manage organization invitations through both the Admin Console and REST API:
-
-* View all sent invitations with their current status (Pending, Expired)
-* Resend pending invitations to recipients
-* Delete invitation records from the system
-* Filter invitations by status for easier management
-
-All invitations are now persistently stored in the database, providing better tracking and management capabilities.
-
-The invitation management features are available in the *Invitations* tab when managing an organization in the Admin Console, and through the Organizations REST API endpoints under `/admin/realms/{realm}/orgs/{orgId}/invitations`.
-
-= Logout confirmation
-
-The client logout configuration page now includes an option to enable logout confirmation. When enabled, users will see "You are logged out" confirmation page upon successful logout.
@@ -12,4 +12,4 @@ Removing the offline scope for a client also removes the ability to issue long-l
 ==== Scope visibility
 
 By default, all scopes are included in the OpenID Connect discovery endpoint.
-To reduce the discoverability and OSINT-exposure, you can configure each scope to be excluded.
+To reduce the discoverability and OSINT-exposure, you can configure each scope to be excluded by disabling *Include in OpenID Provider Metadata*.
@@ -0,0 +1,10 @@
+// ------------------------ Notable changes ------------------------ //
+== Notable changes
+
+Notable changes where an internal behavior changed to prevent common misconfigurations, fix bugs or simplify running {project_name}.
+
+=== User sessions created with "Remember Me" are no longer valid if "Remember Me" is disabled for the realm
+
+When the "Remember Me" option is disabled in the realm settings, all user sessions previously created with the "Remember Me" flag are now considered invalid.
+Users will be required to log in again, and any associated refresh tokens will no longer be usable.
+User sessions created without selecting "Remember Me" are not affected.
@@ -0,0 +1,24 @@
+== 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.
+
+=== Corrected encoding when sending OpenID Connect client secrets when acting as a broker
+
+In a scenario where {project_name} acts as a broker and connects via OpenID Connect to another identity provider, it now sends the client credentials via basic authentication in the correct encoding as specified in RFC6749.
+You are not affected if you configured {project_name} to send the credentials in the request body.
+
+This prevents problems with client IDs or passwords that contain, for example, a colon or a percentage sign.
+
+To revert to the old behavior, change the client authentication to the deprecated option *Client secret sent as HTTP Basic authentication without URL encoding* (`client_secret_basic_unencoded`).
+
+// ------------------------ Deprecated features ------------------------ //
+== Deprecated features
+
+The following sections provide details on deprecated features.
+
+=== Sending OpenID Connect client secret via basic authentication without URL encoding
+
+In a scenario where {project_name} acts as a broker and connects via OpenID Connect to another identity provider, you can choose to send the client secret as *Client secret sent as HTTP Basic authentication without URL encoding* (`client_secret_basic_unencoded`). While this violates RFC6749, it can be used to keep the default behavior of earlier versions of {project_name}.
+
+This behavior is deprecated and will be removed in a future version of Keycloak.
@@ -0,0 +1,59 @@
+// ------------------------ 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.
+
+=== Accepting only normalized paths in requests
+
+Previously {project_name} accepted HTTP requests with paths containing double dots (`..`) or double slashes (`//`). When processing them, it normalized the path by collapsing double slashes and normalized the path according to RFC3986.
+As this has led to a hard-to-configure URL filtering, for example, in reverse proxies, the normalization 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 non-normalized URLs, set the option `http-accept-non-normalized-paths` to `true`. With this configuration, enable and review the HTTP access log to identify problematic requests.
+
+// ------------------------ 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}.
+
+=== Allowing realm administrators granted with the `realm-admin` role to assign admin roles
+
+In previous versions, realm administrators granted with the `realm-admin` role were not able to grant admin roles for delegated realm administrators.
+This was only possible by granting the `admin` role to a master realm user, making this user a server admin.
+
+In this release, realm administrators with the `realm-admin` role can assign admin roles to users in their realm, allowing them to delegate administrative tasks without needing server admin privileges.
+
+If you are using FGAP to delegate administration to users in a realm other than the master realm,
+make sure the users granted with the `realm-admin` role are expected to have this role to avoid privilege scalation.
+
+The documentation is also updated with additional information about the different types of realm administrators.
+For more information, see link:{adminguide_link}#_fine_grained_permissions[Delegating realm administration using permissions].
+
+=== Added database indexes on `OFFLINE_CLIENT_SESSION` table
+
+This adds new indexes on the `OFFLINE_CLIENT_SESSION` table to improve performance when retrieving or deleting client sessions.
+
+If those tables contain 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.
+
+// ------------------------ Deprecated features ------------------------ //
+== Deprecated features
+
+The following sections provide details on deprecated features.
+
+=== Accepting HTTP requests with non-normalized paths
+
+The option `http-accept-non-normalized-paths` was introduced to restore the previous behavior where {project_name} accepted non-normalized URLs.
+
+As this behavior can be problematic for URL filtering, it is deprecated and will be removed in a future release.
+
+// ------------------------ Removed features ------------------------ //
+////
+== Removed features
+
+The following features have been removed from this release.
+
+=== <TODO>
+////
@@ -0,0 +1,21 @@
+// ------------------------ Breaking 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}.
+
+=== LDAP referrals filtered to allow only LDAP referrals
+
+LDAP referrals now by default are only allowed to include LDAP URLs.
+This change enhances security and aligns with best practices for LDAP configurations.
+
+This also prevents other JDNI references from being used in case you have written custom extensions.
+To restore the original behavior, set the option `spi-storage--ldap--secure-referral` to `false`.
+When doing this, we recommend to disable LDAP referrals in all LDAP providers.
+
+== Deprecated features
+
+The following sections provide details on deprecated features.
+
+=== Disabling filtering of LDAP referrals
+
+The option `spi-storage--ldap--secure-referral` to disable filtering referrals is deprecated. It will be removed in a future release and filtering will then be enforced.