Keycloak 26.2.0 release notes

Highlights

Supported Standard Token Exchange

In this release, we added support for the Standard token exchange! The token exchange feature was in preview for a long time, so we are glad to finally support the standard token exchange. For now, this is limited to exchanging the Internal token to internal token compliant with the Token exchange specification. It does not yet cover use cases related to identity brokering or subject impersonation. We hope to support even more token exchange use cases in subsequent releases.

For more details, see the Standard token exchange.

For information on how to upgrade from the legacy token exchange used in previous Keycloak versions, see the Upgrading Guide.

Fine-grained admin permissions supported

This release introduces support for a new version of fine-grained admin permissions. Version 2 (V2) provides enhanced flexibility and control over administrative access within realms. With this feature, administrators can define permissions for administering users, groups, clients, and roles without relying on broad administrative roles. V2 offers the same level of access control over realm resources as the previous version, with plans to extend its capabilities in future versions. Some key points follow:

Centralized Admin Console Management - New Permissions section was introduced to allow management from a single place without having to navigate to different places in the Admin Console.
Improved manageability - Administrators can more easily search and evaluate permissions when building a permission model for realm resources.
Resource-Specific and Global Permissions – Permissions can be defined for individual resources (such as specific users or groups), or entire resource types (such as all users or all groups).
Explicit Operation Scoping – Permissions are now independent, removing hidden dependencies between operations. Administrators must assign each scope explicitly, making it easier to see what is granted without needing prior knowledge of implicit relationships.
Per-Realm Enablement – Fine-Grained Admin Permissions can be enabled on a per-realm basis, allowing greater control over adoption and configuration.

For more details, see fine-grained admin permissions.

For more information about migration, see the Upgrading Guide.

Guides for metrics and Grafana dashboards

In addition to the list of useful metric names the Observability guides category now also contains a guide on how to display these metrics in Grafana. The guide contains two dashboards.

Keycloak troubleshooting dashboard - showing metrics related to service level indicators and troubleshooting.
Keycloak capacity planning dashboard - showing metrics related to estimating the load handled by Keycloak.

Zero-configuration secure cluster communication

For clustering multiple nodes, Keycloak uses distributed caches. Starting with this release for all TCP-based transport stacks, the communication between the nodes is encrypted with TLS and secured with automatically generated ephemeral keys and certificates.

This strengthens a secure-by-default setup and minimizes the configuration steps of new setups.

For more information, check the Securing Transport Stacks in the distributed caches guide.

Rolling updates for optimized and customized images

When using an optimized or customized image, the Keycloak Operator can now perform a rolling update for a new image if the old and the new image contain the same version of Keycloak. This is helpful when you want to roll out, for example, an updated theme or provider without downtime.

To use the functionality in the Operator, enable the Auto update strategy and the Keycloak Operator will on image change briefly start up the old and the new image to determine if a rolling update without downtime is possible. Read the section Managing Rolling Updates in the Keycloak Operator Advanced Configuration guide for more details on this functionality.

The checks to determine if a rolling update is possible are also available on the Keycloak command line so you can use them in your deployment pipeline. Continue reading in the Update Compatibility Tool guide for more information about the functionality available on the command line.

Additional query parameters in Admin Events API

The Admin Events API now supports filtering for events based on Epoc timestamps in addition to the previous yyyy-MM-dd format. This provides more fine-grained control of the window of events to retrieve.

A direction query parameter was also added, allowing controlling the order of returned items as asc or desc. In the past the events where always returned in desc order (most recent events first).

Finally, the returned event representations now also include the id, which provides a unique identifier for an event.

Logs support ECS format

All available log handlers now support ECS (Elastic Common Schema) JSON format. It helps to improve Keycloak’s observability story and centralized logging.

For more details, see the Logging guide.

New cache for CRLs loaded for the X.509 authenticator

Now the Certificate Revocation Lists (CRL), that are used to validate certificates in the X.509 authenticator, are cached inside a new infinispan cache called crl. Caching improves the validation performance and decreases the memory consumption because just one CRL is maintained per source.

Check the crl-storage section in the All provider configuration guide to know the options for the new cache provider.

Operator creates NetworkPolicies to restrict traffic

The Keycloak Operator now creates by default a NetworkPolicy to restrict traffic to internal ports used for Keycloak’s distributed caches.

This strengthens a secure-by-default setup and minimizes the configuration steps of new setups.

You can restrict the access to the management and HTTP endpoints further using the Kubernetes NetworkPolicies rule syntax.

Read more about this in the Operator Advanced configuration.

Option to reload trust and key material for the management interface

The https-management-certificates-reload-period option can be set to define the reloading period of key store, trust store, and certificate files referenced by https-management-* options for the management interface. Use -1 to disable reloading. Defaults to https-certificates-reload-period, which defaults to 1h (one hour).

For more information, check the Configuring the Management Interface guide.

Dynamic Authentication Flow selection using Client Policies

Introduced the ability to dynamically select authentication flows based on conditions such as requested scopes, ACR (Authentication Context Class Reference) and others. This can be achieved using Client Policies by combining the new AuthenticationFlowSelectorExecutor with conditions like the new ACRCondition. For more details, see the Server Administration Guide.

JWT Client authentication aligned with the latest OIDC specification

The latest version of the OpenID Connect Core Specification tightened the rules for audience validation in JWT client assertions for the Client Authentication methods private_key_jwt and client_secret_jwt . Keycloak now enforces by default that there is single audience in the JWT token used for client authentication.

For information on the changed audience validation in JWT Client authentication Keycloak versions, see the Upgrading Guide.

Many thanks to Thomas Darimont for the contribution.

Federated credentials are available now when fetching user credentials

Until now, querying user credentials using the User API will not return credentials managed by user storage providers and, as a consequence, prevent fetching additional metadata associated with federated credentials like the last time a credential was updated.

In this release, we are adding a new method getCredentials(RealmModel, UserModel) to the org.keycloak.credential.CredentialInputUpdater interface so that user storage providers can return the credentials they manage for a specific user in a realm. By doing this, user storage providers can indicate whether the credential is linked to it as well as provide additional metadata so that additional information can be shown when managing users through the administration console.

For LDAP, it should be possible now to see the last time the password was updated based on the standard pwdChangedTime attribute or, if using Microsoft AD, based on the pwdLastSet attribute.

In order to check if a credential is local - managed by Keycloak - or federated, you can check the federationLink property available from both CredentialRepresentation and CredentialModel types. If set, the federationLink property holds the UUID of the component model associated with a given user storage provider.

Token based authentication for SMTP (XOAUTH2)

The Keycloak outgoing SMTP mail configuration now supports token authentication (XOAUTH2). Many service providers (Microsoft, Google) are moving towards SMTP OAuth authentication and end the support for basic authentication. The token is gathered using Client Credentials Grant.

Many thanks to Sebastian Rose for the contribution.

New client configuration for access token header type

A new admin setting has been added: Clients → Advanced → Fine grain OpenID Connect configuration → Use "at+jwt" as access token header type

If enabled, access tokens will get header type at+jwt in compliance with rfc9068#section-2.1. Otherwise, the access token header type will be JWT.

This setting is turned off by default.

Many thanks to Laurids Møller Jepsen for the contribution.

OpenID for Verifiable Credential Issuance documentation

The OpenID for Verifiable Credential Issuance (OID4VCI) remains an experimental feature in Keycloak, but it received further improvements and especially the The documentation, with the steps how to try this feature.

You will find significant development and discussions in the Keycloak OAuth SIG. Anyone from the Keycloak community is welcome to join and provide the feedback.

Many thanks to all members of the OAuth SIG group for the participation in the development and discussions about this feature. Especially thanks to Awambeng Rodrick and Ingrid Kamga.

Upgrading

Before upgrading refer to the migration guide for a complete list of changes.

All resolved issues

New features

#10438 Release process for OperatorHub operator
#17171 Traefik SPI Provider
#35507 Token exchange - permissions token-exchange
#36306 New CLI command: update-compatibility
#36520 New operator spec: upgrade strategy
#36696 Support token type "at+jwt" for OAuth 2 access tokens oidc
#36750 Create CA certificate for JGroups encryption
#38523 Expose OTP Policy in FreeMarker Context for Login Themes login/ui

Enhancements

#17432 Add support for SMTP OAuth 2.0 authentication for outgoing email core
#19127 Improve docs about audience docs
#19148 Token Exchange in "Securing Applications and Services" should mention admin_fine_grained_authz token-exchange
#21728 Removal of X-XSS-Protection header core
#23144 Review and document how refresh tokens are issued when executing token exchanges token-exchange
#24297 Add authentication flow mapping to existing ACR implementation authentication
#25154 `VERIFY_EMAIL` is not supported as an Application Initiated Action
#26473 The way CRLs are currently loaded is slow and uses large amounts of memory authentication
#27734 Use separate OLM channels for each major Keycloak release operator
#28569 Ability to set DN for new users/groups seperate to DN used for search
#30226 Admin-UI: disable Direct Access Grant by default when creating a new client
#31797 Improved consent handling in token exchange (OIDC to OIDC Client) token-exchange
#33357 Create some mechanism to catch duplicate keys in .properties file translations
#33804 Support multiple mail domains for linked IDPs per organization organizations
#33833 Replace `RTL_LANGUAGE_CODE` with Intl request
#33946 Keycloak Admin Client: Close Session when Client is Closed
#34132 Signed SAML metadata saml
#34202 Improve useability of authentication flow UI admin/ui
#34275 Organizations: Allow Organization Selection organizations
#34343 CreatedResponseUtil.getCreatedId should expose the actual error message from the server admin/client-java
#34720 Include broker session ID in IDENTITY_PROVIDER_LOGIN events
#34764 Do not remove users in LDAP when queries return an empty result ldap
#34922 IPv6 support: OLM tests not passing operator
#34971 Extend InfiniSpan ProtoSchema with custom types
#34989 Not email password policy provider: case insensitive comparison
#35505 Support for multiple values of audience token-exchange
#35861 Make client cert lookup honor the `proxy-trusted-addresses` option dist/quarkus
#35901 Document how Keycloak is upgraded when Operator is upgraded via OLM docs
#35995 Review usages of `ref` in `Inject` annotations as they not always translate to the identifier of the object being injected test-framework
#36036 Make Network policy supported
#36126 Add OpenSSF Scorecard badge to README
#36262 Introduce guide for metrics provided by Keycloak docs
#36266 Make user events feature supported
#36440 Remove Node.js adapter documentation from main repo docs
#36456 Clarify IPv6 JGroups requirements in Keycloak documenation
#36501 Upgrade to Quarkus 3.17.x dist/quarkus
#36557 Polishing of CreatedResponseUtil.getCreatedId admin/client-java
#36600 Extend REST API for login and admin events to support sync scenarios
#36671 Translation guide should show a more detailed translation status translations
#36691 Upstream KC main docs to ROSA 4.17 in the sizing guide docs
#36748 Operator: automatic upgrade strategy
#36775 Add option to enable debugging for distribution server mode test-framework
#36786 SPI for compatibility metadata
#36794 Upgrade to Quarkus 3.20 LTS
#36798 Add detail on dependencyManagement section for POM files
#36840 Update Compatibility CLI: add feature flag
#36854 Enable QUARKUS_LOG_JSON_LOG_FORMAT = ecs when logging in Keycloak dist/quarkus
#36885 Improve UX of realm selector
#36904 Add APIResponse annotations to User resources
#36905 Add APIResponse annotations to Role resources
#36906 Add APIResponse annotations to Client Scope resources
#36907 Add APIResponse annotations to Realm resources
#36908 Add APIResponse annotations to Organization resources
#36941 Organization membership for federated users organizations
#36996 Updated translation for "noAccount" in messages_ko.properties
#37005 Login[v2]: Worsen appearance of list of Identity Providers login/ui
#37011 Missing language: Slovenian translations
#37014 Improve readability of relevant options in guides docs
#37034 Remove redundant information from cache entries
#37056 Upgrade to Quarkus 3.18.2 dist/quarkus
#37062 Slow query when checking if a realm has brokers and brokering is enabled identity-brokering
#37079 Improve docs about JPA provider configuration for DB migration strategy core
#37083 Update screens for new realm selector
#37087 Test logs for Quarkus IT are huge and cannot be viewed testsuite
#37089 Stabilize `QuarkusPropertiesDistTest` for Windows in Quarkus IT testsuite
#37093 Avoid sending JSON for user and client sessions to the database
#37129 Create new guide for Keycloak Grafana dashboards
#37145 Simplify translations by removing leading blanks in strings translations
#37220 Operator: new CR status condition for upgrades
#37225 Refactor OAuthClient used for testing test-framework
#37306 Add full Keycloak CR HPA example to docs
#37316 JGroups certificate rotation
#37389 Make event metrics supported
#37416 Operator: Implement an explicit update stategy
#37428 Add a HTML sanitizer for translated message resources translations
#37433 Allow admin to disable automatic refresh of event views admin/ui
#37436 Quarkus 3.19.x upgrade
#37458 Prevent proxy-protocol-enabled=true from being used proxy-headers set
#37535 Add CLOMonitor Badge to the README
#37582 Check surplus blanks in source strings translations
#37584 Support RTL in HTML generated for emails translations
#37624 Suppress info message about mapper config synchronizer core
#37645 Changes needed for new realm selector admin/ui
#37696 Document default key length (2048 bits) and key type (RSA) and make JGroups encryption enabled by default
#37711 Upgrade to Infinispan 15.0.14
#37850 Upgrade to Quarkus 3.19.2 dist/quarkus
#37998 Improve Documentation for Email Event Listner
#38107 Upgrade to Quarkus 3.20.0.CR1
#38168 Make make the rolling updates feature supported versioned and supported
#38212 Improve message when evaluating permission results admin/fine-grained-permissions
#38263 Login[v2]: Use SVG Keycloak logo
#38273 Support partial evaluation for the group resource type admin/fine-grained-permissions
#38355 Add Italian and Romanian language to translations.md
#38366 Polish the events thrown by client policies oidc
#38398 Update javadoc of java admin-client for Keycloak 26.2 admin/client-java
#38415 Login[v2]: WebAuthn/Passkeys screens are not polished
#38426 New realm creation should validate the name uniqueness before hitting the DB
#38445 Not possible to delegate creating or deleting RecoveryKeys credential to userStorage authentication
#38459 Docker image creation simplification
#38490 Support decoding EC private keys and PEM bundles in PEM/DER utilities
#38540 Validate placeholder usage in frontend and backend messages
#38568 Clear persistent user sessions cache on Keycloak cluster merge
#38583 Rework titles in the observability guide
#38596 Prevent NPE in `CryptoIntegration.setProvider(null)`
#38644 Do not allow delete the FGAP client admin/fine-grained-permissions
#38688 Adding a guide on how to use and enable exemplars
#38732 Improvements to partial evaluation admin/fine-grained-permissions
#38764 OTel: Unable to disable sampling at runtime; tracing-sampler-ratio validation prevents setting 0.0 dist/quarkus
#38792 Add Janher to Dutch translation
#38798 Update FGAP documentation admin/fine-grained-permissions
#38819 Make sure that there is single audience allowed by default in JWT tokens sent to client authentication oidc
#38837 Cache resource names associated to policies to improve partial evaluation admin/fine-grained-permissions

Bugs

#26104 Improper Input Validation for Recovery Codes Setup authentication
#26105 Users Can Change Recovery Codes Generation Timestamp authentication
#26106 Recovery Code Validation Race Possible authentication
#29585 Passkeys conditional UI authenticator: NullPointerException when filling some random username authentication/webauthn
#29586 Passkeys conditional UI authenticator: NullPointerException when authenticated as removed user authentication/webauthn
#32262 SAML Frontchannel Logout missing via Redirect or Post Binding is missing signature if login happened via artifact binding saml
#32535 Invalid migration export for empty database core
#32766 Translation error in messages_fr.properties translations
#32921 Update realm erases browser security header fields admin/api
#33332 External token (not issued by Keycloak) cannot be validated in token exchange flow in case user info check is disabled token-exchange
#33432 UI Build complains about Typescript issue (TS2742) admin/ui
#33475 quarkus-next: SunCertPathBuilderException: unable to find valid certification path to requested target ci
#33477 LDAP groups not showing members in Groups when using memberOf attribute ldap
#33524 Social login - several tests failing constantly ci
#33743 Linked accounts displayed when there are no providers available account/ui
#34364 User import gets exponentially slow import-export
#34396 com.google.code.findbugs:jsr305 is old and no longer under active maintenance dependencies
#34454 quarkus-next: StackOverflowError causes build failure dist/quarkus
#34512 Keycloak OpenAPI specification doesn't match actual API implementation admin/api
#34868 [Jenkins Operator CI] - Test remote - ClusteringTest on OpenShift ci
#35020 Pasword creation date from active directory is wrong ldap
#35261 liveness probe /health/live not UP while DB migrations initialization core
#35580 AvailableRoleMappingResource.listAvailableUserRoleMappings returns the wrong roles when using fine grained permissions admin/fine-grained-permissions
#35700 Very uncommon new german Weblate translation 'Berechtigungsnachweis' for login data /account credential translations
#35833 Install on oracle database with custom schema fails on clean install storage
#36103 Translation resolution bug in keycloak-admin-ui admin/ui
#36159 Realm not found while exists and works if entered directly in the URL admin/ui
#36195 CVE-2024-12397 - HTTP Request Smuggling in io.quarkus.http:quarkus-http-core dist/quarkus
#36284 Fail to import realm during the startup with specific name file import-export
#36285 Permission editor shows resource IDs instead of names admin/ui
#36338 Scrollbar missing so I can't scroll to the last menu item on the left admin/ui
#36345 [Keycloak CI] - Cookies tests - KcOidcBrokerTokenExchangeTest ci
#36383 Operator tests failing on IPV6 environment operator
#36405 Redirect after linking account account/ui
#36409 Verify email required action shows presents message that email was sent even on errors core
#36413 Empty state in new events tabs admin/ui
#36447 ClientProtocolCondition.getProviderId() typo authentication
#36460 Deployment artifacts for Quarkus extensions are not in deployment dir dist/quarkus
#36464 Remove a duplicate code block
#36475 DPoP: Refresh token created with DPoP can be refreshed without proof oidc
#36476 DPoP: User Info Endpoint authorization type mismatch oidc
#36478 Spelling and grammar mistakes in admin UI messages admin/ui
#36482 The root cause of error is suppressed in KC 26 at building dependencies
#36483 Wrong link for tracing in 26.1.0 release notes docs
#36486 ExternalLinksTest is broken after Keycloak 26.1.0 release docs
#36498 Duplicated code due to typo in DefaultHttpClientFactory core
#36514 The organization claim does not appear if the Organization Membership Mapper is added through a custom client scope organizations
#36517 Custom ClientAuthenticatorFactory with ProviderConfigProperty broken admin/ui
#36518 Duplicate groups needs fine grained authorisation admin/ui
#36527 Viewing user events requires `view-realm`-role admin/ui
#36531 WebAuthN and dark mode: device icons are hardly readable login/ui
#36535 Duplicate message keys for FA email template translations
#36541 Unable to build from source using instructions core
#36559 keycloak.v2 forms are too small for mobile view login/ui
#36560 Policy enforcer do not handle suppressed server resources authorization-services

These notes run past the length kept in the archive. The rest is on the publisher’s page.