Keycloak 26.2.0 released

April 11 2025

To download the release go to Keycloak downloads.

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 link:Configuring email for a realm[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

Enhancements

Bugs