Release Notes

Starting with Keycloak 26, the Organizations feature is fully supported.

Keycloak 25 introduced the feature persistent-user-sessions. With this feature enabled all user sessions are persisted in the database as opposed to the previous behavior where only offline sessions were persisted. In Keycloak 26, this feature is enabled by default. This means that all user sessions are persisted in the database by default.

It is possible to revert this behavior to the previous state by disabling the feature. Follow the Volatile user sessions section in Configuring distributed caches guide for more details.

For information on how to upgrade, see the Upgrading Guide.

There is now a new version (v2) of the keycloak login theme, which provides an improved look and feel, including support for switching automatically to a dark theme based on user preferences.

The previous version (v1) is now deprecated, and will be removed in a future release.

For all new realms, keycloak.v2 will be the default login theme. Also, any existing realm that never explicitly set a login theme will be switched to keycloak.v2.

Keycloak 26 introduces significant improvements to the recommended HA multi-site architecture, most notably:

For information on how to migrate, see the Upgrading Guide.

In the past, regaining access to a Keycloak instance when all admin users were locked out was a challenging and complex process. Recognizing these challenges and aiming to significantly enhance the user experience, Keycloak now offers several straightforward methods to bootstrap a temporary admin account and recover lost admin access.

It is now possible to run the start or start-dev commands with specific options to create a temporary admin account. Additionally, a new dedicated command has been introduced, which allows users to regain admin access without hassle.

For detailed instructions and more information on this topic, refer to the Admin Bootstrap and Recovery guide.

The underlying Quarkus support for OpenTelemetry Tracing has been exposed to Keycloak and allows obtaining application traces for better observability. It helps to find performance bottlenecks, determine the cause of application failures, trace a request through the distributed system, and much more. The support is in preview mode, and we would be happy to obtain any feedback.

For more information, see the Enabling Tracing guide.

The OpenID for Verifiable Credential Issuance (OID4VCI) is still an experimental feature in Keycloak, but it was greatly improved in this release. You will find significant development and discussions in the Keycloak OAuth SIG. Anyone from the Keycloak community is welcome to join.

Many thanks to all members of the OAuth SIG group for the participation on the development and discussions about this feature. Especially thanks to the Francis Pouatcha, Pascal Knüppel, Takashi Norimatsu, Ingrid Kamga, Stefan Wiedemann and Thomas Darimont

The DPoP (OAuth 2.0 Demonstrating Proof-of-Possession) preview feature has improvements. The DPoP is now supported for all grant types. With previous releases, this feature was supported only for the authorization_code grant type. Support also exists for the DPoP token type on the UserInfo endpoint.

Many thanks to Pascal Knüppel for the contribution.

GELF support has been deprecated for a while now, and with this release it has been finally removed from Keycloak. Other log handlers are available and fully supported to be used as a replacement of GELF, for example Syslog. For details see the Logging guide.

Lightweight access tokens can now be used on the admin REST API. The security-admin-console and admin-cli clients are now using lightweight access tokens by default, so “Always Use Lightweight Access Token” and “Full Scope Allowed” are now enabled on these two clients. However, the behavior in the admin console should effectively remain the same. Be cautious if you have made changes to these two clients and if you are using them for other purposes.

Keycloak JavaScript adapter is now a standalone library and is therefore no longer served statically from the Keycloak server. The goal is to de-couple the library from the Keycloak server, so that it can be refactored independently, simplifying the code and making it easier to maintain in the future. Additionally, the library is now free of third-party dependencies, which makes it more lightweight and easier to use in different environments.

For a complete breakdown of the changes consult the Upgrading Guide.

The deprecated hostname v1 feature was removed. This feature was deprecated in Keycloak 25 and replaced by hostname v2. If you are still using this feature, you must migrate to hostname v2. For more details, see the Configuring the hostname (v2) and the initial migration guide.

User is automatically redirected to the path where Keycloak is hosted when the http-relative-path property is specified. It means when the relative path is set to /auth, and the user access localhost:8080/, the page is redirected to localhost:8080/auth.

The same applies to the management interface when the http-management-relative-path or http-relative-path property is specified.

It improves user experience as users no longer need to set the relative path to the URL explicitly.

In this release, revoked access tokens are written to the database and reloaded when the cluster is restarted by default when using the embedded caches.

For information on how to migrate, see the Upgrading Guide.

The condition based on the client-attribute was added into Client Policies. You can use condition to specify for the clients with the specified client attribute having a specified value. It is possible to use either an AND or OR condition when evaluating this condition as mentioned in the documentation for client policies.

Many thanks to Yoshiyuki Tabata for the contribution.

It is possible to specify log levels for all available log handlers, such as console, file, or syslog. The more fine-grained approach provides the ability to control logging over the whole application and be tailored to your needs.

For more information, see the Logging guide.

The deprecated proxy option was removed. This option was deprecated in Keycloak 24 and replaced by the proxy-headers option in combination with hostname options as needed. For more details, see using a reverse proxy and the initial migration guide.

The proxy-trusted-addresses can be used when the proxy-headers option is set to specify a allowlist of trusted proxy addresses. If the proxy address for a given request is not trusted, then the respective proxy header values will not be used.

The proxy-protocol-enabled option controls whether the server should use the HA PROXY protocol when serving requests from behind a proxy. When set to true, the remote address returned will be the one from the actual connecting client.

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

The --cache-embedded-${CACHE_NAME}-max-count= can be set to define an upper bound on the number of cache entries in the specified cache.

Based on the community feedback, we decided to undeprecate https-trust-store-* options to allow better granularity in trusted certificates.

The java-keystore key provider, which allows loading a realm key from an external java keystore file, has been modified to manage all Keycloak algorithms. Besides, the keystore and key secrets, needed to retrieve the actual key from the store, can be configured using the vault. Therefore a Keycloak realm can externalize any key to the encrypted file without sensitive data stored in the database.

For more information about this subject, see Configuring realm keys.

Now Keycloak allows configuring ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW or ECDH-ES+A256KW as the encryption key management algorithm for clients. The Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES) specification introduces three new header parameters for the JWT: epk, apu and apv. Currently Keycloak implementation only manages the compulsory epk while the other two (which are optional) are never added to the header. For more information about those algorithms please refer to the JSON Web Algorithms (JWA).

Also, a new key provider, ecdh-generated, is available to generate realm keys and support for ECDH algorithms is added into the Java KeyStore provider.

Many thanks to Justin Tay for the contribution.

It is now possible to have multiple instances of the same social broker in a realm.

Most of the time a realm does not need multiple instances of the same social broker. But due to the introduction of the organization feature, it should be possible to link different instances of the same social broker to different organizations.

When creating a social broker, you should now provide an Alias and optionally a Display name just like any other broker.

There are now generalized events for updating (UPDATE_CREDENTIAL) and removing (REMOVE_CREDENTIAL) a credential. The credential type is described in the credential_type attribute of the events. The new event types are supported by the Email Event Listener.

The following event types are now deprecated and will be removed in a future version: UPDATE_PASSWORD, UPDATE_PASSWORD_ERROR, UPDATE_TOTP, UPDATE_TOTP_ERROR, REMOVE_TOTP, REMOVE_TOTP_ERROR

The template.ftl file in the base/login and the keycloak.v2/login theme now allows to customize the footer of the login box. This can be used to show common links or include custom scripts at the end of the page.

The new footer.ftl template provides a content macro that is rendered at the bottom of the "login box".

The Keycloak CR now exposes first class properties for controlling the scheduling of your Keycloak Pods.

For more details, see the Operator Advanced Configuration.

The KeycloakRealmImport CR now exposes spec.placeholders to create environment variables for placeholder replacement in the import.

For more details, see the Operator Realm Import.

In this release, the LDAP connection pool configuration relies solely on system properties.

For more details, see Configuring the connection pool.

Marshalling is the process of converting Java objects into bytes to send them across the network between Keycloak servers. With Keycloak 26, we changed the marshalling format from JBoss Marshalling to Infinispan Protostream.

Infinispan Protostream is based on Protocol Buffers (proto 3), which has the advantage of backwards/forwards compatibility.

Since all of the Java adapters that used OSGi metadata have been removed we have stopped generating OSGi metadata for our jars.

With the goal of improving the scalability of groups, they are now removed directly from the database when removing a realm. As a consequence, group-related events like the GroupRemovedEvent are no longer fired when removing a realm.

For information on how to migrate, see the Upgrading Guide.

As part of the improvements around the scalability of realms and organizations when they have many identity providers, the realm representation no longer holds the list of identity providers. However, they are still available from the realm representation when exporting a realm.

For information on how to migrate, see the Upgrading Guide.

The Securing Applications and Services documentation was converted into the new format similar to the Server Installation and Configuration documentation converted in the previous releases. The documentation is now available under Keycloak Guides.

Keycloak no longer sends _LEGACY cookies, which where introduced as a work-around to older browsers not supporting the SameSite flag on cookies.

The _LEGACY cookies also served another purpose, which was to allow login from an insecure context. Although, this is not recommended at all in production deployments of Keycloak, it is fairly frequent to access Keycloak over http outside of localhost. As an alternative to the _LEGACY cookies Keycloak now doesn’t set the secure flag and sets SameSite=Lax instead of SameSite=None when it detects an insecure context is used.

The origin property in the UserRepresentation is deprecated and planned to be removed in future releases.

Instead, prefer using the federationLink property to obtain the provider to which a user is linked with.

The Account Console v2 theme has been removed from Keycloak. This theme was deprecated in Keycloak 24 and replaced by the Account Console v3 theme. If you are still using this theme, you should migrate to the Account Console v3 theme.

Keycloak now supports OpenJDK 21, as we want to stick to the latest LTS OpenJDK versions.

OpenJDK 17 support is deprecated in Keycloak, and will be removed in a following release in favor of OpenJDK 21.

As stated in the release notes of previous Keycloak version, the most of Java adapters are now removed from the Keycloak codebase and downloads pages.

For OAuth 2.0/OIDC, this includes removal of the Tomcat adapter, WildFly/EAP adapter, Servlet Filter adapter, KeycloakInstalled desktop adapter, the jaxrs-oauth-client adapter, JAAS login modules, Spring adapter and SpringBoot adapters. You can check our older post for the list of some alternatives.

For SAML, this includes removal of the Tomcat adapter and Servlet filter adapter. SAML adapters are still supported with WildFly and JBoss EAP.

The generic Authorization Client library is still supported, and we still plan to support it. It aims to be used in combination with any other OAuth 2.0 or OpenID Connect libraries. You can check the quickstarts for some examples where this authorization client library is used together with the 3rd party Java adapters like Elytron OIDC or SpringBoot. You can check the quickstarts also for the example of SAML adapter used with WildFly.

In Keycloak 24, the Welcome page is updated to use PatternFly 5, the latest version of the design system that underpins the user interface of Keycloak. In this release, the Admin Console and Account Console are also updated to use PatternFly 5. If you want to extend and customize the Admin Console and Account Console, review the changes in PatternFly 5 and update your customizations accordingly.

Argon2 is now the default password hashing algorithm used by Keycloak in a non-FIPS environment.

Argon2 was the winner of the 2015 password hashing competition and is the recommended hashing algorithm by OWASP.

In Keycloak 24 the default hashing iterations for PBKDF2 were increased from 27.5K to 210K, resulting in a more than 10 times increase in the amount of CPU time required to generate a password hash. With Argon2 it is possible to achieve better security, with almost the same CPU time as previous releases of Keycloak. One downside is Argon2 requires more memory, which is a requirement to be resistant against GPU attacks. The defaults for Argon2 in Keycloak requires 7MB per-hashing request. To prevent excessive memory and CPU usage, the parallel computation of hashes by Argon2 is by default limited to the number of cores available to the JVM. To support the memory intensive nature of Argon2, we have updated the default GC from ParallelGC to G1GC for a better heap utilization.

Note that Argon2 is not compliant with FIPS 140-2. So if you are in the FIPS environment, the default algorithm will be still PBKDF2. Also note that if you are on non-FIPS environment and you plan to migrate to the FIPS environment, consider changing the password policy to a FIPS compliant algorithm such as pbkdf2-sha512 at the outset. Otherwise, users will not be able to log in after they switch to the FIPS environment.

In response to the complexity and lack of intuitiveness experienced with previous hostname configuration settings, we are proud to introduce Hostname v2 options.

We have listened to your feedback, tackled the tricky issues, and created a smoother experience for managing hostname configuration. Be aware that even the behavior behind these options has changed and requires your attention - if you are dealing with custom hostname settings.

Hostname v2 options are supported by default, as the old hostname options are deprecated and will be removed in the following releases. You should migrate to them as soon as possible.

New options are activated by default, so Keycloak will not recognize the old ones.

For information on how to migrate, see the Upgrading Guide.

Previous versions of Keycloak stored only offline user and offline client sessions in the databases. The new feature persistent-user-sessions stores online user sessions and online client sessions not only in memory, but also in the database. This will allow a user to stay logged in even if all instances of Keycloak are restarted or upgraded.

The feature is a preview feature and disabled by default. To use it, add the following to your build command:

For more details see the Enabling and disabling features guide. The sizing guide contains a new paragraph describing the updated resource requirements when this feature is enabled.

For information on how to upgrade, see the Upgrading Guide.

The following APIs for setting custom cookies have been removed:

The Keycloak 23 release provided improvements for when a user is authenticated in parallel in multiple browser tabs. However, this improvement did not address the case when an authentication session expired. Now for the case when user is already logged-in in one browser tab and an authentication session expired in other browser tabs, Keycloak is able to redirect back to the client application with an OIDC/SAML error, so the client application can immediately retry authentication, which should usually automatically log in the application because of the SSO session. For more details, see Server Administration Guide authentication sessions.

In previous releases, the support for lightweight access token was added. In this release, we managed to remove even more built-in claims from the lightweight access token. The claims are added by protocol mappers. Some of them affect even the regular access tokens or ID tokens as they were not strictly required by the OIDC specification.

For more details, see the Upgrading Guide..

You can use the HTTP Header Accept: application/jwt when invoking a token introspection endpoint. When enabled for a particular client, it returns a claim jwt from the token introspection endpoint with the full JWT access token, which can be useful especially for the use-cases when the client calling introspection endpoint used lightweight access token. Thanks to Thomas Darimont for the contribution.

Keycloak supports a new password policy that allows you to deny user passwords which contains the user username.

In the Admin Console, you can now configure some required actions in the Required actions tab of a particular realm. Currently, the Update password is the only built-in configurable required action. It supports setting Maximum Age of Authentication, which is the maximum time users can update their password by the kc_action parameter (used for instance when updating password in the Account Console) without re-authentication. The sorting of required actions is also improved. When there are multiple required actions during authentication, all actions are sorted together regardless of whether those are actions set during authentication (for instance by the kc_action parameter) or actions added to the user account manually by an administrator. Thanks to Thomas Darimont and Daniel Fesenmeyer for the contributions.

The support for Passkeys conditional UI was added. When the Passkeys preview feature is enabled, there is a dedicated authenticator available, which means you can select from a list of available passkeys accounts and authenticate a user based on that. Thanks to Takashi Norimatsu for the contribution.

The default client profile to have secured SAML clients was added. When browsing through client policies of a realm in the Admin Console, you see a new client profile saml-security-profile. When it is used, there are security best practices applied for SAML clients such as signatures are enforced, SAML Redirect binding is disabled, and wildcard redirect URLs are prohibited.

There was new authenticator Confirm override existing link added. This authenticator allows to override linked IDP username for the Keycloak user, which was already linked to different IDP identity before. More details in the Server Administration Guide. Thanks to Lex Cao for the contribution.

There is work in progress on the support of OpenID for Verifiable Credential Issuance (OID4VCI). Right now, this is still work in progress, but things are being gradually added. Keycloak can act as an OID4VC Issuer with support of Pre-Authorized code flow. There is support for verifiable credentials in the JWT-VC, SD-JWT-VC and VCDM formats. Thanks to the members of the OAuth SIG groups for the contributions and feedback and especially thanks to Stefan Wiedemann, Francis Pouatcha, Takashi Norimatsu and Yutaka Obuchi.

When searching for users by user attribute, Keycloak no longer searches for user attribute names forcing lower case comparisons. The goal of this change was to speed up searches by using Keycloak’s native index on the user attribute table. If your database collation is case-insensitive, your search results will stay the same. If your database collation is case-sensitive, you might see less search results than before.

For users of the keycloak-authz-client library, calling AuthorizationResource.getPermissions(…​) now correctly returns a List<Permission>.

Previously, it would return a List<Map> at runtime, even though the method declaration advertised List<Permission>.

This fix will break code that relied on casting the List or its contents to List<Map>. If you have used this method in any capacity, you are likely to have done this and be affected.

When exporting the authorization settings for a client, the IDs for resources, scopes, and policies are no longer set. As a result, you can now import the settings from a client to another client.

Metrics and health checks endpoints are no longer accessible through the standard Keycloak server port. As these endpoints should be hidden from the outside world, they can be accessed on a separate default management port 9000.

It allows to not expose it to the users as standard Keycloak endpoints in Kubernetes environments. The new management interface provides a new set of options and is fully configurable.

Keycloak Operator assumes the management interface is turned on by default. For more details, see Configuring the Management Interface.

Keycloak now supports Syslog protocol for remote logging. It utilizes the protocol defined in RFC 5424. By default, the syslog handler is disabled, but when enabled, it sends all log events to a remote syslog server.

For more information, see the Configuring logging guide.

The method EnvironmentDependentProviderFactory.isSupported() was deprecated for several releases and has now been removed.

For more details, see the Upgrading Guide.

It is now possible to specify the cache, cache-stack, and cache-config-file options during runtime. This eliminates the need to execute the build phase and rebuild your image due to them.

For more details, see the Upgrading Guide.

The high availability guide now contains a guide on how to configure an AWS Lambda to prevent an intended automatic failback from the Backup site to the Primary site.

In this release, we are finally removing deprecated methods from the following classes:

For more details, see the Upgrading Guide.

As a consequence of the removal of deprecated methods from AccessToken, IDToken, and JsonWebToken, the SingleUseObjectKeyModel also changed to keep consistency with the method names related to expiration values.

For more details, see the Upgrading Guide.

The supported and tested databases now include PostgreSQL 16.

In this release, we are delivering Keycloak Organizations as a technology preview feature.

This feature provides a realm with some core CIAM capabilities, which will serve as the baseline for more capabilities in the future to address Business-to-Business (B2B) and Business-to-Business-to-Customers (B2B2C) use cases.

In terms of functionality, the feature is completed. However, we still have work to do to make it fully supported in the next major release. This remaining work is mainly about preparing the feature for production deployments with a focus on scalability. Also, depending on the feedback we get until the next major release, we might eventually accept additional capabilities and add more value to the feature, without compromising its roadmap.

For more details, see Server Administration Guide.

This release contains the fix of the important security issue affecting some OIDC confidential clients using PAR (Pushed authorization request). In case you use OIDC confidential clients together with PAR and you use client authentication based on client_id and client_secret sent as parameters in the HTTP request body (method client_secret_post specified in the OIDC specification), it is highly encouraged to rotate the client secrets of your clients after upgrading to this version.

When updating user attributes through the Admin User API, you cannot execute partial updates when updating the user attributes, including the root attributes like username, email, firstName, and lastName.

For more details, see the Upgrading Guide.

Due to an issue in the release process when deploying Keycloak using the Operator it installed the nightly container instead of 24.0.0.

As a quick fix to the issue, the 24.0.0 container was tagged with nightly, and the nightly releases was temporarily disabled.

If you installed or upgraded to 24.0.0 using the Operator before 5pm CET yesterday the database may have been updated with the wrong versions. To check if you are affected connect to your database and run the following SQL command:

If the above returns a matching row you will need to take some actions, otherwise database migrations will not run for future releases. To resolve this run the following SQL command:

The user profile preview feature is promoted to be fully supported and user profile is enabled by default.

In the past months, the Keycloak team spent a huge amount of effort in polishing the user profile feature to make it fully supported. In this release, we continued the effort. Lots of improvements, fixes and polishing were done based on the thorough testing and feedback from our awesome community.

The following are a few highlights of this feature;

The first release of the user profile as a supported feature is just the starting point and the baseline for delivering many more capabilities around identity management.

We would like to give huge thanks to the awesome Keycloak community as lots of ideas, requirements and contributions came from the community! Special thanks to:

For more details about user profile capabilities, see the Server Administration Guide.

Back in 2022 we announced the deprecation of Keycloak adapters in Keycloak 19. To give the community more time to adopt this was delayed.

With that in mind, this will be the last major release of Keycloak to include OpenID Connect and SAML adapters. As Jetty 9.x has not been supported since 2022 the Jetty adapter has been removed already in this release.

The generic Authorization Client library will continue to be supported, and aims to be used in combination with any other OAuth 2.0 or OpenID Connect libraries.

The only adapter we will continue to deliver is the SAML adapter for latest releases of WildFly and EAP 8.x. Reasoning for continuing to support this is down to the fact that the majority of the SAML codebase in Keycloak was a contribution from WildFly. As part of this contribution we agreed to maintain SAML adapters for WildFly and EAP in the long run.

The 'welcome' page that appears at the first use of Keycloak is redesigned. It provides a better setup experience and conforms to the latest version of PatternFly. The simplified page layout includes only a form to register the first administrative user. After completing the registration, the user is sent directly to the Admin Console.

If you use a custom theme, you may need to update it to support the new welcome page. For details, see the Upgrading Guide.

We introduced version 3 of the Account Console in Keycloak 22 as a preview feature. In this release, we are making it the default version, and deprecating version 2 in the process, which will be removed in a subsequent release.

This new version has built-in support for the user profile feature, which allows administrators to configure which attributes are available to users in the Account Console, and lands a user directly on their personal account page after logging in.

If you are using or extending the customization features of this theme, you may need to perform additional migrations. For more details, see the Upgrading Guide.

In this release, we adapted the password hashing defaults to match the OWASP recommendations for Password Storage.

As part of this change, the default password hashing provider has changed from pbkdf2-sha256 to pbkdf2-sha512. Also, the number of default hash iterations for pbkdf2 based password hashing algorithms changed. This change means better security aligned with latest recommendations, but it has impact on performance. It is possible to stick to the old behaviour by adding password policies hashAlgorithm and hashIterations to your realm. For more details, see the Upgrading Guide.

The CORS related Keycloak functionality was extracted into the SPI, which can allow additional flexibility. Note that CorsSPI is internal and may change at a future release. Thanks to Dmitry Telegin for the contribution.

Keycloak introduces improved truststores configuration options. The Keycloak truststore is now used across the server, including outgoing connections, mTLS, and database drivers. You no longer need to configure separate truststores for individual areas. To configure the truststore, you can put your truststores files or certificates in the default conf/truststores, or use the new truststore-paths config option. For details refer to the relevant guide.

Features now support versioning. To preserve backward compatibility, all existing features (including account2 and account3) are marked as version 1. Newly introduced features will use versioning, which means that users can select between different implementations of desired features.

For details refer to the features guide.

The SAML identity providers can now be configured to automatically download the signing certificates from the IDP entity metadata descriptor endpoint. In order to use the new feature, configure the Metadata descriptor URL option in the provider (the URL where the IDP metadata information with the certificates is published) and set Use metadata descriptor URL to ON. The certificates are automatically downloaded and cached in the public-key-storage SPI from that URL. The certificates can also be reloaded or imported from the Admin Console, using the action combo in the provider page.

See the documentation for more details about the new options.

A new health check endpoint available at /lb-check was added. The execution is running in the event loop, which means this check is responsive also in overloaded situations when Keycloak needs to handle many requests waiting in request queue. This behavior is useful, for example, in multi-site deployment to avoid failing over to another site that is under heavy load. The endpoint is currently checking availability of the embedded and external Infinispan caches. Other checks may be added later.

This endpoint is not available by default. To enable it, run Keyloak with the multi-site feature. For more details, see Enabling and disabling features.

The Keycloak CR now includes an startOptimized field, which may be used to override the default assumption about whether to use the --optimized flag for the start command. As a result, you can use the CR to configure build time options also when a custom Keycloak image is used.

It is now possible to separately enable parsing of either Forwarded or X-Forwarded-* headers by using the new --proxy-headers option. For details, see the Reverse Proxy Guide. The original --proxy option is now deprecated and will be removed in a future release. For migration instructions, see the Upgrading Guide.

In this release, we are encapsulating the root user attributes (such as username, email, firstName, lastName, and locale) by moving them to a base/abstract class in order to align how these attributes are marshalled and unmarshalled when using both Admin and Account REST APIs.

This strategy provides consistency in how attributes are managed by clients and makes sure they conform to the user profile configuration set to a realm.

For more details, see the Upgrading Guide.

Starting with this release, the first member of a Keycloak cluster will load remote sessions sequentially instead of in parallel. If offline session preloading is enabled, those will be loaded sequentially as well.

For more details, see the Upgrading Guide.

In this release, you can no longer perform actions such as email verification if the user is already authenticated and the action is bound to another user. For instance, a user can not complete the verification email flow if the email link is bound to a different account.

In this release, if a user tries to follow the link to verify the email and the email was previously verified, a proper message will be shown.

In addition to that, a new error (EMAIL_ALREADY_VERIFIED) event will be fired to indicate an attempt to verify an already verified email. You can use this event to track possible attempts to hijack user accounts in case the link has leaked or to alert users if they do not recognize the action.

The default behavior of Keycloak is to load offline sessions on demand. The old behavior to preload them at startup is now deprecated, as pre-loading them at startup does not scale well with a growing number of sessions, and increases Keycloak memory usage. The old behavior will be removed in a future release.

For more details, see the Upgrading Guide.

To reduce memory requirements, we introduced a configuration option to shorten lifespan for offline sessions imported into the Infinispan caches. Currently, the offline session lifespan override is disabled by default.

For more details, see the Server Administration Guide.

When enabling metrics for Keycloak’s embedded caches, the metrics now use labels for the cache manager and the cache names.

For more details, see the Upgrading Guide.

As of this release, Keycloak supports storing and searching by user attribute values longer than 255 characters, which was previously a limitation.

For more details, see the Upgrading Guide.

There have been a couple of enhancements to the Brute Protection:

In previous versions of Keycloak, when the last member of a User, Group or Client policy was deleted then that policy would also be deleted. Unfortunately this could lead to an escalation of privileges if the policy was used in an aggregate policy. To avoid privilege escalation the effect policies are no longer deleted and an administrator will need to update those policies.

The Keycloak CR now allows for specifying the cache-config-file option by using the cache spec configMapFile field, for example:

The Keycloak CR now allows for specifying the resources options for managing compute resources for the Keycloak container. It provides the ability to request and limit resources independently for the main Keycloak deployment via the Keycloak CR, and for the realm import Job via the Realm Import CR.

When no values are specified, the default requests memory is set to 1700MiB, and the limits memory is set to 2GiB.

You can specify your custom values based on your requirements as follows:

For more details, see the Operator Advanced configuration.

There is now a new event USER_DISABLED_BY_TEMPORARY_LOCKOUT when a user is temporarily locked out by the brute force protector. The log with ID KC-SERVICES0053 has been removed as the new event offers the information in a structured form.

For more details, see the Upgrading Guide.

Cookie handling code has been refactored and improved, including a new Cookie Provider. This provides better consistency for cookies handled by Keycloak, and the ability to introduce configuration options around cookies if needed.

User Attribute Mapper For NameID allowed setting Name ID Format option to the following values:

However, Keycloak does not support receiving AuthnRequest document with one of these NameIDPolicy, therefore these mappers would never be used. The supported options were updated to only include the following Name ID Formats:

Instead of specifying hardcoded values for the initial and maximum heap size, Keycloak uses relative values to the total memory of a container. The JVM options -Xms and -Xmx were replaced by -XX:InitialRAMPercentage and -XX:MaxRAMPercentage.

For more details, see the Upgrading Guide.

With sunsetting of the underlying library providing integration with GELF, Keycloak will no longer support the GELF log handler out-of-the-box. This feature will be removed in a future release. If you require an external log management, consider using file log parsing.

Deploying Keycloak to multiple independent sites is essential for some environments to provide high availability and a speedy recovery from failures. This release supports active-passive deployments for Keycloak.

To get started, use the High Availability Guide which also includes a comprehensive blueprint to deploy a highly available Keycloak to a cloud environment.

Declarative user profile is still a preview feature in this release, but we are working hard on promoting it to a supported feature. Feedback is welcome. If you find any issues or have any improvements in mind, you are welcome to create Github issue, ideally with the label area/user-profile. It is also recommended to check the Upgrading Guide with the migration changes for this release for some additional information related to the migration.

Performance around searching of groups is improved for the use-cases with many groups and subgroups. There are improvements, which allow paginated lookup of subgroups. Thanks to Alice for the contribution.

A security vulnerability was introduced in Keycloak 22.0.2. We highly recommend not upgrading to 22.0.2, and for anyone that has deployed 22.0.2 in production to upgrade to 22.0.3 immediately.

For users that has self-registered after Keycloak was upgraded to 22.0.2 their password is not stored securely, and can be exposed to administrators of Keycloak. This only affects users that has registered after the upgrade was rolled-out, and does not affect any previously registered users.

Any realm using the preview declarative user profile is not affected by this issue, and only realms using the default user profile provider is affected.

To identify if there are any affected users in your deployment you can query these by accessing the database, and running the following SQL statement:

We recommend contacting any affected users as well as adding the update password required action for them.

If there are any affected users we also recommend removing these attributes from the database by running the following SQL statement:

If any backups have been done of the database after the 22.0.2 release and there are affected users, we recommend deleting these.

Keycloak now supports multiple LDAP providers in a realm, which support Kerberos integration with the same Kerberos realm. When an LDAP provider is not able to find the user which was authenticated through Kerberos/SPNEGO, Keycloak ties to fallback to the next LDAP provider. Keycloak has also better support for the case when single LDAP provider supports multiple Kerberos realms, which are in trust with each other.

The openshift-integration preview feature that allowed replacing the internal IdP in OpenShift 3.x with Keycloak was removed from Keycloak codebase into separate extension project.

If an application client is using non http(s) custom schemes, from now on the validation requires that a valid redirect pattern explicitly allows that scheme. Example patterns for allowing custom scheme are custom:/test, custom:/test/* or custom:*. For security reasons a general pattern like * does not cover them anymore.

In the past Keycloak was maintained across multiple GitHub repositories:

Having multiple repositories introduced a lot of complexity and toil. For example frequently multiple pull requests had to be sent to different repositories for a single change.

To simplify things we have now migrated everything into the main repository.

FIPS 140-2 support in Keycloak, which was preview in the previous release, is now promoted to be officially supported.

The Account Console version 3 is now available as an experimental feature in Keycloak. This version supports custom fields created with the 'User Profile' feature. If you are looking to try it out and provide us with some early feedback you can enable it as follows:

As part of the removal of the deprecated adapters, the Keycloak Policy Enforcer was extracted from the adapters code base into a separate dependency:

By providing this dependency, we expect making it possible to integrate the policy enforcer with the Java stack of your preference.

It also provides built-in support for enabling the policy enforcer to Jakarta applications protected with Wildfly Elytron.

For now, this dependency is not yet GA as we are still working on the quickstarts and documentation.

This work should not impact existing applications using the deprecated adapters. = Javascript engine available by default

In the previous version, when Keycloak was used on Java 17 with Javascript providers it was needed to add the Nashorn javascript engine to the distribution. This is no longer needed as Nashorn javascript engine is available in Keycloak server by default.

In Keycloak 19 the new admin console was graduated to the new default admin console, and the old admin console was deprecated. In this release the old admin console has been removed completely.

Keycloak provides an optional a metrics endpoint which exports metrics in the Prometheus format. In this release the implementation to provide this data switched from SmallRye to Micrometer. Due to this change, metrics have been renamed.

See the migration guide for details.

Running the Keycloak server with Java 11 is now deprecated, and planned to be removed in Keycloak 22.

Adapters remain supported on Java 8, Java 11, and Java 17. However, we are planning to remove support for Java 8 in the not too distant future.

We removed the out-of-box support for Hashicorp vault in this release.

See this discussion for more details.

Prior to this release, SAML SP metadata contained the same key for both signing and encryption use. Starting with this version of Keycloak, we include only encryption intended realm keys for encryption use in SP metadata. For each encryption key descriptor we also specify the algorithm that it is supposed to be used with. The following table shows the supported XML-Enc algorithms with the mapping to Keycloak realm keys. See the Upgrading Guide for more details.

Several deprecated methods were removed from user session provider. If not done already, their usage needs to be replaced with the corresponding replacement documented in Javadoc of Keycloak 20 release. See Upgrading Guide for more details.

The IS_CLIENT_ROLE searchable field from the RoleModel was deprecated. It should be replaced with the CLIENT_ID searchable field used with the operators EXISTS or NOT_EXISTS. See JavaDoc of Keycloak 21 for more details.

FIPS 140-2 support in Keycloak, which was experimental in the previous release, is now promoted to preview. There were many fixes and improvements to create this preview version. For the details, see the FIPS documentation. Feedback is welcome!

Thanks again to David Anderson, Sudeep Das and Isaac Jensen for their huge help with this feature.

In addition to recognize the non-standard X-Forwarded-* to fetch information added by proxies that would otherwise be altered or lost when proxy servers are involved in the path of the request, Keycloak can now leverage the standard Forwarded header for the same purpose.

For more details, see the Using a reverse proxy guide.

Please, make sure your proxy is also overriding the Forwarded header when making requests to Keycloak nodes.

To enhance security, the Keycloak Container Image has been modified in two ways: First, it is now based on UBI9, rather than UBI8. Second, we have switched to -micro, whereas -minimal was used before.

The change to UBI9 will not have any impact on most users. In rare cases the glibc error CPU does not support x86-64-v2 may appear. x86-64-v2 has been available from processors since 2009. You’re most likely to encounter this issue when your virtualization environment is misconfigured.

The change from -minimal to -micro has more potential impact. Users making simple customizations to the image won’t notice any difference, however any user that installs RPMs will need to change how they do that. The Running Keycloak in a container guide has been updated to show you how.

As a result of these changes, there has been an 82% reduction in known CVEs affecting the Keycloak Container Image!

In Keycloak 17.0.0 the new Quarkus based distribution of Keycloak, while the WildFly based distribution was deprecated. With this release the WildFly distribution has been removed, and is no longer supported.

If you are still using the WildFly distribution we highly encourage migrating to the Quarkus distribution as soon as possible, see the Migration Guide for more details.

We are happy to announce that the new Keycloak Operator for the Quarkus based distribution is no longer a preview feature. We added new functionality as well as a number of improvements, some which has resulted in breaking changes.

Keycloak now supports OpenJDK 17 both for the server and adapters.

With the removal of the WildFly based distribution there is no longer support for running the Keycloak server on OpenJDK 8. We also plan to remove support for Keycloak adapters on OpenJDK 8 in Keycloak 21.

Starting with Keycloak 22 we plan to only support the latest OpenJDK LTS release and aiming to quickly also support the latest OpenJDK release. That means we will be also removing OpenJDK 11 support for the Keycloak server in Keycloak 22.

In this release, we are introducing two additional server options to set the base URL for frontend request and the Admin Console:

More details can be found at the Configuring the Hostname guide.

In this release, we are making important changes to kc.bat to give the same experience as when running on Linux.

Keycloak ships for development purposes with an H2 database driver. As it is intended for development purposes only, it should never be used in a production environment.

In this release, the H2 driver has been upgraded from version 1.x to version 2.x.

Applications are able to load keycloak.js directly from the Keycloak server. As it’s not considered a best-practice to load JavaScript libraries this way there is now a feature guard that allows disabling this ability.

In Keycloak 21 we will deprecate this option, and in Keycloak 22 we plan to completely remove the ability to load keycloak.js from the Keycloak server.

In previous releases the list of OTP applications displayed to users was hard-coded in Keycloak. With the introduction of the OTP Application SPI it is now possible to disable built-in OTP applications, as well as adding custom OTP Applications.

A custom identity provider can now set the icon used on the login pages. Thanks to Klaus Betz, who happens also to maintain an extension to Keycloak to support log in with AppleID.

There is now experimental support for deploying Keycloak into a FIPS 140-2 enabled environment. There will be a blog post with the details shortly after the release with the details how you can try it. Feedback is welcome!

Thanks to David Anderson, who contributed parts of this feature. Also, thanks to Sudeep Das and Isaac Jensen for their initial prototype effort, which was used as an inspiration.

It is now possible to search groups by attribute through the Admin REST API. Thanks to Alice for this contribution.

It is now possible to allow users to view their group memberships in the account console. Thanks to cgeorgilakis for this contribution.

Several deprecated methods were removed from data providers and models. If not done already, their usage needs to be replaced with the corresponding replacement documented in Javadoc of Keycloak 19 release. See Upgrading Guide for more details.

Some Keycloak OpenID Connect adapters have reached end-of-life and are not included in this release.

The new Admin Console is now graduated to the default admin console, with the old console now deprecated. The old console will be removed in Keycloak 21.

The Keycloak storage is changing, and the current storage, while still supported, will eventually be replaced with a brand-new implementation. This change brings better support for cloud-native storages, no-downtime abilities, and better support for implementing custom storages for additional areas apart from users.

It means several deep changes in the supported features of the current store will become legacy features. The legacy store and the new store cannot be used simultaneously; only one store can be active at a time.

The most visible change is that the User Storage SPI is incompatible with the new storage API, the Map Storage API. Thus, the User Storage SPI will be deprecated with legacy store and will move to a separate module called keycloak-model-legacy. This change impacts several areas, especially areas related to user federation and custom user providers.

Furthermore, APIs have been consolidated so that the details of the storage layer will be transparent to the REST service layer. Specifically, the services will not be able to differentiate cached and non-cached objects, nor specifically access federated versus local storage.

Hence, custom extensions that access objects in local storage or cache through KeycloakSession methods must be reviewed. See Upgrading Guide for details.

In the previous release, we added support for OIDC logout. This release contains a few other fixes and polishing. The highlights include:

For more details, see the Server Administration Guide.

There is new preview feature UPDATE_EMAIL. When it is enabled and corresponding flag enabled in the realm, the users will be required to confirm updating their email by clicking the link, which will be sent to their new email address. For more details, see the Server Administration Guide. Thanks to Réda Housni Alaoui for the contribution.

With this release, we have deprecated podDisruptionBudget field in the Keycloak CR of the legacy Keycloak Operator. This optional field will be ignored when the Operator is deployed on Kubernetes version 1.25 and higher.

As a workaround, you can manually create the Pod Disruption Budget in your cluster, for example:

See also the Kubernetes Documentation.

Starting with version 19, Keycloak supports sending logs using GELF to centralized logging solutions like ELK, EFK or Graylog out of the box.

You can find the documentation and examples to get you up and running quickly in the logging guide.

With this release, we’re introducing a brand new Keycloak Operator as a preview. Apart from being rewritten from scratch, the main user-facing change from the legacy Operator is the used Keycloak distribution – the new Operator uses the Quarkus distribution of Keycloak. With that, the API (in form of Custom Resource Definitions) has changed. For details, incl. installation and migration instructions, see the Operator related guides.

The legacy Operator will receive updates until Keycloak 20 when the Keycloak WildFly distribution reaches EOL.

The new Admin Console is now graduated to preview, with the plan for it to become the default admin console in Keycloak 19.

If you find any issues with the new console, or have some suggestions for improvements, please let us know through GitHub Discussions.

Keycloak now supports Step-up authentication. This feature was added in Keycloak 17, and was further polished in this version.

For more details, see Server Administration Guide.

Thanks to Cornelia Lahnsteiner and Georg Romstorfer for the contribution.

Keycloak now supports Client Secret Rotation through customer policies. This feature is now available as a preview feature and allows that confidential clients can be provided with realm policies allowing the use up to two secrets simultaneously.

For more details, see Server Administration Guide.

Recovery Codes as another way to do two-factor authentication is now available as a preview feature.

Some fixes and improvements were made to make sure that Keycloak is now fully compliant with all the OpenID Connect logout specifications:

For more details, see Server Administration Guide.

Keycloak now supports WebAuthn id-less authentication. This feature allows that WebAuthn Security Key will identify the user during authentication as long as the security key supports Resident Keys. For more details, see Server Administration Guide. Thanks to Joaquim Fellmann for the contribution.

There are more WebAuthn improvements and fixes in addition to that.

The upload-script feature has been marked as deprecated for a very long time. In this release, it was completely removed, and it is no longer supported.

If you are using any of these capabilities:

You should consider reading this documentation in order to understand how to still rely on these capabilities but deploying your scripts to the server rather than managing them through the management interfaces.

Keycloak now supports limits on the number of sessions a user can have. Limits can be placed at the realm level or at the client level.

For more details, see Server Administration Guide. Thanks to Mauro de Wit for the contribution.

To mitigate the risk of abusing SAML ECP Profile, Keycloak now blocks this flow for all SAML clients that do not allow it explicitly. The profile can be enabled using Allow ECP Flow flag within client configuration, see Server Administration Guide.

This release contains some important bug fixes. In addition, We would like to thank Leandro José de Bortoli for his contributions to the FAPI related functionalities such as JARM support and improvements in CIBA.

Until now, administrators were allowed to upload scripts to the server through the Keycloak Administration Console as well as through the RESTful Admin API.

For now on, this capability is disabled by default and users should prefer to deploy scripts directly to the server. For more details, please take a look at JavaScript Providers.

Keycloak server was upgraded to use WildFly 16 under the covers.

Thanks to tnorimat Keycloak now has support for signing and verifying tokens with PS256.

New built-in client scope to make it easy to issue tokens following the Eclipse MicroProfile specification.

Keycloak server was upgraded to use WildFly 15 under the covers.

It is now possible to fully secure OpenShift 3.11 with Keycloak, including the ability to automatically expose Service Accounts as OAuth clients as clients to Keycloak.

This is currently a technology preview feature.

Until now, Drools policies were enabled by default. But now, this policy type is only available as a technology preview feature and to use it you need to enable the preview profile or the corresponding feature. Take a look at the Authorization Services Guide for more details.

DB2 support has been deprecated for a while. With this release we have removed all support for DB2.

Introduced the ability to specify different session idle and max timeouts for remember me sessions. This enables remember me sessions to live longer than regular sessions.

Large numbers of groups have previously caused issues in the admin console. This is now resolved by the introduction of pagination of groups.

In the past, starting the server could take a long time if there were many offline sessions. This startup time has now been significantly reduced.

The Keycloak server was upgraded to use WildFly 14 under the covers.

Keycloak Gatekeeper provides a security proxy that can be used to secure applications and services without an adapter. It can be installed locally alongside your application or as a sidecar on OpenShift or Kubernetes.

Huge thanks to gambol99 for contributing this work to Keycloak.

The Signature SPI makes it possible to plug-in additional signature algorithms. This enables additional signatures and also enables changing how signatures are generated. For example, using this allows using an HSM device to sign tokens.

Thanks to tnorimat for contributing a significant part of this work.

Alongside the Signature SPI there is now also support for additional signature algorithms.

Keycloak now has support for RS256, RS384, RS512, ES256, ES384, ES512, HS256, HS384 and HS512.

Elliptic Curve Digital Signature Algorithm (ES256/384/512) are very interesting as they provide similar security properties as RSA signatures, but use significantly less CPU.

HMAC (HS256/384/512) are also very useful when you do not want your application to verify the signature itself. Since these are symmetric signatures only Keycloak is able to verify the signature, which requires the application to use the token introspection endpoint to verify tokens.

Thanks to tnorimat for contributing a significant part of this work.

It is now possible to specify the audiences in the tokens issued for OpenID Connect clients. There is also support for verification of audience on the adapter side.

The Keycloak server was upgraded to use WildFly 13 under the covers. This means update of the underlying dependencies and also some changes in the configuration. We now also support WildFly 13 adapter and we upgraded the underlying JDG/Infinispan server version for the Cross-DC setup. See Upgrading Guide for more details.

Having authorization services support in Node.js makes it very easy to do fine-grained central authorization with the Node.js adapter.

The hostname SPI introduces a more flexible way to configure the hostname for Keycloak. There are two built-in providers. The first is request, which uses the request headers to determine the hostname. The second is fixed, which allows configuring a fixed hostname. The latter makes sure that only valid hostnames can be used and also allows internal applications to invoke Keycloak through an alternative URL.

For more details refer to the threat mitigation section in the Server Administration Guide.

The newly added Client Authenticator uses X509 Client Certificates and Mutual TLS to secure a connection from the client. In addition to that the Keycloak Server validates Subject DN field of the client’s certificate.

For this release, we improved policy evaluation performance across the board, increasing reliability and throughput. The main changes we did were related with trying to optimize the policy evaluation path by avoiding unnecessary flows and collect decisions as soon as they happen. We also introduced a policy decision cache on a per-request basis, avoiding redundant decisions from policies previously evaluated.

We are also working on other layers of cache which should give a much better experience. See KEYCLOAK-7952.

In previous versions, permissions were always returned from the server using standard OAuth2 response, containing the access and refresh tokens. In this release, clients can use a response_mode parameter to specify how the server should respond to an authorization request. This parameter accepts two values:

The keycloak-nodejs-connect, an adapter for NodeJS, now supports constructs to protect resources based on decisions taken from the server. The new construct allows users to protect their resources using fine-grained permissions as follows:

Login with Google now supports the hd parameter to restrict Google logins to a specific hosted domain at Google. When this is specified in the identity provider any login from a different domain is rejected.

Thanks to brushmate for the contribution.

Most HTML output is already escaped for HTML tags, but there are some places where HTML tags are permitted. These are only where admin access is needed to update the value. Even though it would require admin access to update such fields we have added an extra layer of defence and are now escaping unsafe elements like <script>.

We now have support for using browser tab and universal links in the JavaScript adapter for Cordova. This enables SSO between multiple applications as well as increases security.

Thanks to gtudan for the contribution.

The SAML adapter can support multi-tenancy now just like the built-in adapter for OpenID Connect.

In previous versions, it was not possible to create claims in the token using a claim name containing a dot (.) character. Now it is possible to escape the dot character in the configuration, so a claim name with the dot character can be used.

Starting with release 4.1, the Spring Boot starter will be based on the Spring Boot 2 adapter. If you are using an older Spring Boot version, the keycloak-legacy-spring-boot-starter is available.

We added support for Client Scopes, which replaces Client Templates. Client Scopes are a more flexible approach and also provides better support for the OAuth scope parameter.

There are changes related to Client Scopes to the consent screen. The list on the consent screen is now linked to client scopes instead of protocol mappers and roles.

See the documentation and migration guide for more details.

We now have a partial implementation of the specification OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens . More accurately we have support for the Certificate Bound Access Tokens. If your confidential client is able to use 2-way SSL, Keycloak will be able to add the hash of the client certificate into the tokens issued for the client. At this moment, it’s just the Keycloak itself, which verifies the token hashes (for example during refresh token requests). We plan to add support to adapters as well. We also plan to add support for Mutual TLS Client Authentication.

Thanks to tnorimat for the contribution.

It is now possible to hot-deploy themes to Keycloak through a regular provider deployment. We have also added support for theme resources, which allows adding additional templates and resources without creating a theme. This is useful for custom authenticators that require additional pages to be added to the authentication flow.

We have also added support to override the theme for specific clients. If that is not adequate for your needs, then there is also a new Theme Selector SPI that allows you to implement custom logic to select the theme.

We have added support to login with Instagram. Thanks to hguerrero for the contribution.

To search for a user by id in the admin console you previously had to edit the URL. It is now possible to search directly in the user search field.