You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/documentation/release_notes/topics/26_5_0.adoc
+96-31Lines changed: 96 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,92 @@
1
1
// Release notes should contain only headline-worthy new features,
2
2
// assuming that people who migrate will read the upgrading guide anyway.
3
3
4
-
= Preview of enhanced HTTP performance
4
+
////
5
+
6
+
// TODO
7
+
This release features new capabilities focused on ... The highlights of this release are:
8
+
9
+
// TODO
10
+
// ...
11
+
12
+
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].
13
+
14
+
////
15
+
16
+
= Security and Standards
17
+
18
+
== Logout confirmation page
19
+
20
+
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.
For the OpenID Connect Dynamic Client Registration, you can now specify which CORS headers are allowed via the client registration access policies.
27
+
28
+
For the overall CORS configuration, you can now allow environment specific headers to be allowed using the SPI option `+spi-cors--default--allowed-headers+`.
29
+
30
+
== Hiding OpenID Connect scopes from the discovery endpoint
Previously, all scopes of an OpenID Connect client were advertised in the discovery endpoint.
34
+
35
+
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.
36
+
37
+
You can now prevent this by disabling *Include in OpenID Provider Metadata*.
38
+
39
+
= Administration
40
+
41
+
////
42
+
// TODO
43
+
= Federated client authentication (preview)
44
+
////
45
+
46
+
== Organization invitation management
47
+
48
+
Organization administrators can now manage organization invitations through both the Admin Console and REST API:
49
+
50
+
* View all sent invitations with their current status (Pending, Expired)
51
+
* Resend pending invitations to recipients
52
+
* Delete invitation records from the system
53
+
* Filter invitations by status for easier management
54
+
55
+
All invitations are now persistently stored in the database, providing better tracking and management capabilities.
56
+
57
+
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+`.
58
+
59
+
== New event `USER_SESSION_DELETED`
60
+
61
+
For each expired user session there is a new user event `USER_SESSION_DELETED` fired.
62
+
This event is published approximately 3-10 minutes after the session has expired depending on job scheduling and load on the system.
63
+
By default, this event is not persisted.
64
+
65
+
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.
66
+
This should allow for better response times when there are a lot of sessions in the table.
67
+
68
+
= Configuring and Running
69
+
70
+
== Containers for PowerPC 64-bit Little Endian architecture
71
+
72
+
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.
73
+
74
+
We expect this to allow users to optimize their usage of open hardware and power consumption.
75
+
76
+
== Session cache affinity
77
+
78
+
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.
79
+
80
+
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.
81
+
82
+
== PostgreSQL version updates
83
+
84
+
The latest major release of PostgreSQL 18 is now supported.
85
+
As PostgreSQL 13 is end-of-life it is now longer supported.
86
+
87
+
We also updated the docs on how to use a TLS certificate for the JDBC-connection when connecting to a PostgreSQL database.
88
+
89
+
== Enhanced HTTP performance (preview)
5
90
6
91
You can now enable a more efficient way to handle JSON data in the HTTP layer.
7
92
This change increases throughput by ~5%, stabilizes response times, and reduces system resource usage.
@@ -15,13 +100,19 @@ endif::[]
15
100
16
101
For more details, see the https://www.keycloak.org/server/configuration-production[Configuring Keycloak for production] guide.
17
102
18
-
= Breaking Fix for Windows in Loopback Hostname Verification
103
+
== Enable/disable features via a single option
19
104
20
-
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.
105
+
You can now enable or disable individual features using the `feature-<name>` option (like `feature-spiffe=enabled`).
21
106
22
-
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.
107
+
This provides a more fine-grained way to manage features and eliminates the need to maintain long lists of enabled or disabled features.
23
108
24
-
= Export traces with custom request headers
109
+
The `feature-<name>` option takes precedence over both `features` and `features-disabled`.
110
+
111
+
For more details, see the https://www.keycloak.org/server/features[Enabling and disabling features] guide.
112
+
113
+
= Observability
114
+
115
+
== Export traces with custom request headers
25
116
26
117
It is now possible to set request headers for exporting traces via Open Telemetry Protocol (OTLP).
27
118
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,
30
121
31
122
For more details, see the link:{tracingguide_link}[{tracingguide_name}] guide.
32
123
33
-
= Enable/disable features via a single option
34
-
35
-
You can now enable or disable individual features using the `feature-<name>` option (like `feature-spiffe=enabled`).
36
-
37
-
This provides a more fine-grained way to manage features and eliminates the need to maintain long lists of enabled or disabled features.
38
-
39
-
The `feature-<name>` option takes precedence over both `features` and `features-disabled`.
40
-
41
-
For more details, see the https://www.keycloak.org/server/features[Enabling and disabling features] guide.
42
-
43
124
== MDC Logging feature (supported)
44
125
45
126
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
48
129
49
130
For more details, see the https://www.keycloak.org/server/logging#_adding_context_for_log_messages[Adding context for log messages] guide.
50
131
51
-
= Organization invitation management
52
-
53
-
Organization administrators can now manage organization invitations through both the Admin Console and REST API:
54
-
55
-
* View all sent invitations with their current status (Pending, Expired)
56
-
* Resend pending invitations to recipients
57
-
* Delete invitation records from the system
58
-
* Filter invitations by status for easier management
59
-
60
-
All invitations are now persistently stored in the database, providing better tracking and management capabilities.
61
-
62
-
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`.
63
-
64
-
= Logout confirmation
65
-
66
-
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.
Notable changes where an internal behavior changed to prevent common misconfigurations, fix bugs or simplify running {project_name}.
5
+
6
+
=== User sessions created with "Remember Me" are no longer valid if "Remember Me" is disabled for the realm
7
+
8
+
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.
9
+
Users will be required to log in again, and any associated refresh tokens will no longer be usable.
10
+
User sessions created without selecting "Remember Me" are not affected.
Breaking changes are identified as those that might require changes for existing users to their configurations or applications.
4
+
In minor or patch releases, {project_name} will only introduce breaking changes to fix bugs.
5
+
6
+
=== Corrected encoding when sending OpenID Connect client secrets when acting as a broker
7
+
8
+
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.
9
+
You are not affected if you configured {project_name} to send the credentials in the request body.
10
+
11
+
This prevents problems with client IDs or passwords that contain, for example, a colon or a percentage sign.
12
+
13
+
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`).
14
+
15
+
// ------------------------ Deprecated features ------------------------ //
16
+
== Deprecated features
17
+
18
+
The following sections provide details on deprecated features.
19
+
20
+
=== Sending OpenID Connect client secret via basic authentication without URL encoding
21
+
22
+
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}.
23
+
24
+
This behavior is deprecated and will be removed in a future version of Keycloak.
Breaking changes are identified as those that might require changes for existing users to their configurations or applications.
5
+
In minor or patch releases, {project_name} will only introduce breaking changes to fix bugs.
6
+
7
+
=== Accepting only normalized paths in requests
8
+
9
+
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.
10
+
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.
11
+
12
+
To analyze rejected requests in the server log, enable debug logging for `org.keycloak.quarkus.runtime.services.RejectNonNormalizedPathFilter`.
13
+
14
+
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 may include internal behavior changes that prevent common misconfigurations, bugs that are fixed, or changes to simplify running {project_name}.
20
+
21
+
=== Allowing realm administrators granted with the `realm-admin` role to assign admin roles
22
+
23
+
In previous versions, realm administrators granted with the `realm-admin` role were not able to grant admin roles for delegated realm administrators.
24
+
This was only possible by granting the `admin` role to a master realm user, making this user a server admin.
25
+
26
+
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.
27
+
28
+
If you are using FGAP to delegate administration to users in a realm other than the master realm,
29
+
make sure the users granted with the `realm-admin` role are expected to have this role to avoid privilege scalation.
30
+
31
+
The documentation is also updated with additional information about the different types of realm administrators.
32
+
For more information, see link:{adminguide_link}#_fine_grained_permissions[Delegating realm administration using permissions].
33
+
34
+
=== Added database indexes on `OFFLINE_CLIENT_SESSION` table
35
+
36
+
This adds new indexes on the `OFFLINE_CLIENT_SESSION` table to improve performance when retrieving or deleting client sessions.
37
+
38
+
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.
39
+
See the link:{upgradingguide_link}[{upgradingguide_name}] for details on how to configure a different limit.
40
+
41
+
// ------------------------ Deprecated features ------------------------ //
42
+
== Deprecated features
43
+
44
+
The following sections provide details on deprecated features.
45
+
46
+
=== Accepting HTTP requests with non-normalized paths
47
+
48
+
The option `http-accept-non-normalized-paths` was introduced to restore the previous behavior where {project_name} accepted non-normalized URLs.
49
+
50
+
As this behavior can be problematic for URL filtering, it is deprecated and will be removed in a future release.
51
+
52
+
// ------------------------ Removed features ------------------------ //
53
+
////
54
+
== Removed features
55
+
56
+
The following features have been removed from this release.
Notable changes may include internal behavior changes that prevent common misconfigurations, bugs that are fixed, or changes to simplify running {project_name}.
5
+
6
+
=== LDAP referrals filtered to allow only LDAP referrals
7
+
8
+
LDAP referrals now by default are only allowed to include LDAP URLs.
9
+
This change enhances security and aligns with best practices for LDAP configurations.
10
+
11
+
This also prevents other JDNI references from being used in case you have written custom extensions.
12
+
To restore the original behavior, set the option `spi-storage--ldap--secure-referral` to `false`.
13
+
When doing this, we recommend to disable LDAP referrals in all LDAP providers.
14
+
15
+
== Deprecated features
16
+
17
+
The following sections provide details on deprecated features.
18
+
19
+
=== Disabling filtering of LDAP referrals
20
+
21
+
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.
0 commit comments