When using for example a one-time-password (OTP) generators as a second factor for authenticating users (2FA), a user can get locked out of their account when they, for example, lose their phone that contains the OTP generator. To prepare for such a case, the recovery codes feature allows users to print a set of recovery codes as an additional second factor. If the recovery codes are then allowed as an alternative 2FA in the login flow, they can be used instead of the OTP generated passwords.

With this release, the recovery codes feature is promoted from preview to a supported feature. For newly created realms, the browser flow now includes the Recovery Authentication Code Form as Disabled, and it can be switched to Alternative by admins if they want to use this feature.

For more information about this 2FA method, see the Recovery Codes chapter in the Server Administration Guide.

The time it takes to run imports, exports or migrations involving a large number of realms has been improved. There is no longer a cumulative performance degradation for each additional realm processed.

Both WebAuthn Register actions (webauthn-register and webauthn-register-passwordless) which are also used for Passkeys now support a parameter skip_if_exists when initiated by the application (AIA).

This should make it more convenient to use the AIA in scenarios where a user has already set up WebAuthn or Passkeys. The parameter allows skipping the action if the user already has a credential of that type.

For more information, see the Registering WebAuthn credentials using AIA chapter in the Server Administration Guide.

Client-initiated linking a user account to the identity provider is now based on application-initiated action (AIA) implementation. This functionality aligns configuring this functionality and simplifies the error handling the calling of the client application, making it more useful for a broader audience.

The custom protocol, which was previously used for client-initiated account linking, is now deprecated.

In previous releases Keycloak already supported federation with other OpenID Connect and SAML providers, as well as with several Social Providers like GitHub and Google which are based on OAuth 2.0.

The new OAuth 2.0 broker now closes the gap to federate with any OAuth 2.0 provider. This then allows you to federate, for example, with Amazon or other providers. As this is a generic provider, you will need to specify the different claims and a user info endpoint in the provider’s configuration.

For more information, see the OAuth v2 identity providers chapter in the Server Administration Guide.

Until now, the OpenID Connect broker did not support the standard email_verified claim available from the ID Tokens issued by OpenID Connect Providers.

Starting with this release, Keycloak supports this standard claim as defined by the OpenID Connect Core Specification for federation.

Whenever users are federated for the first time or re-authenticating and if the Trust email setting is enabled, Sync Mode is set to FORCE and the provider sends the email_verified claim, the user account will have their email marked according to the email_verified claim. If the provider does not send the claim, it defaults to the original behavior and sets the email as verified.

All available log handlers now support asynchronous logging capabilities. Asynchronous logging helps deployments that require high throughput and low latency.

For more details on this opt-in feature, see the Logging guide.

In the previous release, the Keycloak Operator was enhanced to support performing rolling updates of the Keycloak image if both images contain the same version. This is useful, for example, when switching to an optimized image, changing a theme or a provider source code.

In this release, we extended this to perform rolling update when the new image contains a future patch release from the same major.minor release stream as a preview feature. This can reduce the service’s downtime even further, as downtime is only needed when upgrading from a different minor or major version.

Read more on how to enable this feature in update compatibility command.

In this release Keycloak integrates Passkeys in the default authentications forms. A new switch Enable Passkeys is available in the configuration, Authentication → Policies → Webauthn Passwordless Policy, that seamlessly incorporates passkeys support to the realm. With just one click, Keycloak offers conditional and modal user interfaces in the default login forms to allow users to authenticate with a passkey.

The Passkeys feature is still in preview. Follow the Enabling and disabling features guide to enable it.

For more information, see Passkeys section in the Server Administration Guide.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.