Release Notes

Any deployments with custom user storage federation providers may also be affected, please verify your custom user storage to identify if this is an issue.

To identify if there are any federated user affected in your deployment in case the user storage provider is delegating management of attributes to Keycloak, you can query these by accessing the database, and running the following SQL statement:

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

If your custom user storage provider is managing attributes itself, you should look at your custom storage to remove the password and password-confirm attributes.

Running the Keycloak server with Java 11 is no longer supported. Java 11 was deprecated in Keycloak 21 with the announced plan to be removed in Keycloak 22.

Keycloak upgraded to version 3.2.0.Final of the Quarkus Java framework. Quarkus 3.x continues the tradition of propelling Java development by moving fast and providing a cutting-edge user experience with the latest technologies.

Keycloak now benefits from the upgrade to Hibernate ORM 6.2, which includes improved performance, better SQL, modern JDK support, and support for modern RDBMS features.

The previous and now removed WildFly distribution provided a built-in vault provider that reads secrets from a keystore-backed Elytron credential store. As this is no longer available, we have added a new implementation of the Keycloak Vault SPI called Keycloak KeyStore Vault. As the name suggests, this implementation reads secrets from a Java keystore file. Such secrets can be then used within multiple places of the Administration Console. For further details, see our guide and the latest documentation.

In relation to the KeyStore Vault news, we also integrated Quarkus’s recently released feature called KeyStore Config Source. This means that among the already existing configuration sources (CLI parameters, environment variables and files), you can now configure your Keycloak server via configuration properties stored in a Java keystore file. You can learn more about this feature in the Configuration guide.

As a number of users have had problems with configuring the hostname for the server correctly there is now a new helper tool to allow debugging the configuration.

Installations which use Keycloak’s --proxy configuration setting with mode passthrough should review the documentation as the behavior of this mode has changed.

In previous releases, the export and import commands required a build command to be run first. Starting with this release, the export and import commands perform an automatic rebuild of Keycloak if a build time configuration has changed.

The old Account Console (v1) is now completely removed. This version of the Account Console was marked as deprecated in Keycloak 12.

In version 21.1.0 of Keycloak the new Account Console (version 3) was introduced as an experimental feature. Starting this version it has been promoted to a preview feature.

Two of the variables exposed to the Account Console V2 and V3 templates (isEventsEnabled and isTotpConfigured) were left unused, and have been removed in this release.

It is possible that if a developer extended the Account Console theme, he or she could make use of these variables. So make sure that these variables are no longer used if you are extending the base theme.

The Admin Console (and soon also the new Account Console) works slightly different than the rest of Keycloak in regards to how keys for internationalized messages are parsed. This is due to the fact that it uses the i18next library for internationalization. Therefore when defining custom messages for the Admin Console under "Realm Settings" ➡ "Localization" best practices for i18next must be taken into account. Specifically, when defining a message for the Admin Console it is it important to specify a namespace in the key of your message.

For example, let’s assume we want to overwrite the welcome message shown to the user when a new realm has been created. This message is located in the dashboard namespace, same as the name of the original file that holds the messages (dashboard.json). If we wanted to overwrite this message we’ll have to use the namespace as a prefix followed by the key of the message separated by a colon, in this case it would become dashboard:welcome.

With this release, we have removed the legacy Promise API methods from the Keycloak JS adapter. This means that calling .success() and .error() on promises returned from the adapter is no longer possible.

In a previous release we started to actively log deprecation warnings when the Keycloak JS adapter is constructed without the new operator. Starting this release doing so will throw an exception instead. This is to align with the expected behavior of JavaScript classes, which will allow further refactoring of the adapter in the future.

After the upgrade to Jakarta EE, artifacts for Keycloak Admin clients were renamed to more descriptive names with consideration for long-term maintainability. We still provide two separate Keycloak Admin clients, one with Jakarta EE and the other with Java EE support.

The User API now supports querying the number of users based on custom attributes. For that, a new q parameter was added to the /{realm}/users/count endpoint.

The q parameter expects the following format q=<name>:<value> <name>:<value>. Where <name> and <value> represent the attribute name and value, respectively.

The are additional fields available in the keycloak.status to facilitate keycloak being a scalable resource. There are also additional fields that make the status easier to interpret such as observedGeneration and condition observedGeneration and lastTransitionTime fields.

The condition status field was changed from a boolean to a string for conformance with standard Kubernetes conditions. In the CRD it will temporarily be represented as accepting any content, but it will only ever be a string. Please make sure any of your usage of this field is updated to expect the values "True", "False", or "Unknown", rather than true or false.

In scenarios where advanced management is needed you may now directly update most fields on operator managed resources that have not been set by the operator directly. This can be used as an alternative to the unsupported stanza of the Keycloak spec. Like the unsupported stanza these direct modifications are not considered supported. If your modifications prevent the operator from being able to manage the resource, there Keycloak CR will show this error condition and the operator will log it.

OpenID Connect identity providers support a new configuration to specify that the ID tokens issued by the identity provider must have a specific claim, otherwise the user can not authenticate through this broker.

The option is disabled by default; when it is enabled, you can specify the name of the JWT token claim to filter and the value to match (supports regular expression format).

The OpenID Connect providers now support Json Web Encryption (JWE) for the ID Token and the UserInfo response. The providers use the realm keys defined for the selected encryption algorithm to perform the decryption.

The new hardcorded group mapper allows adding a specific group to users brokered from an Identity Provider.

The new user session note mapper allows mapping a claim to the user session notes.

LDAP option to use truststore SPI Only for ldaps has been removed. This parameter is used to select truststore for TLS-secured LDAP connection: either internal Keycloak truststore is picked (Always), or the global JVM one (Never).

Deployments where Only for ldaps was used will automatically behave as if Always option was selected for TLS-secured LDAP connections.

As the new Operator currently lacks some of the CRs (e.g. Client and User), we’re introducing a temporary workaround in the form of a Realm Operator. Please see its GitHub Repository for more details. See also "The future of Keycloak Operator CRs" blogpost.

Keycloak will no longer be providing adapters for Fuse 6 or 7. If you need adapters for Fuse please leverage Red Hat Single Sign-On 7.x adapters.

JBoss AS 7 has been unmaintained for a very long time. If you are still using JBoss AS 7 we recommend migrating to WildFly and leveraging the native OIDC support in WildFly.

Red Hat customers using Red Hat JBoss Enterprise Application Platform 6.x should use Red Hat Single Sign-On 7.x adapters. These can be used in combination with the Keycloak server.

Jetty 9.2 reached end of life in 2018, while Jetty 9.3 reached end of life in 2020. If you are still using these versions we recommend upgrading to Jetty 9.4 as soon as possible.

Spring Boot 1.x reached end of life in 2019. If you are still using Spring Boot 1 we recommend upgrading to Spring Boot 2 as soon as possible.

In WildFly 25 the legacy security layer was removed, going forward only Elytron will be supported. We recommend anyone using an older version of WildFly to upgrade and leverage native OIDC support in WildFly.

Red Hat customers using Red Hat JBoss Enterprise Application Platform 7.x should use Red Hat Single Sign-On 7.x adapters. These can be used in combination with the Keycloak server.

To avoid version conflicts with the legacy Operator, the 18.0.0 version of the new Operator is released as version 20.0.0-alpha.1 on OperatorHub. The legacy Operator versioning scheme remains the same, i.e. it is released as 18.0.0.

The same pattern will apply for future Keycloak 18 and 19 releases, until version 20 where the legacy Operator reaches EOL.

The Keycloak Quarkus distribution now supports importing your realms directly at start-up. For more information, check the corresponding guide.

The Keycloak Quarkus distribution now initially supports logging to a File and logging structured data using JSON.

For more information on the improvements, check the corresponding Logging guide.

You can now change the port of your jdbc connection string explicitly by setting the new db-url-port configuration option. As for the other convenience options, this option will be overridden by the value of a full db-url, if set.

The metrics-enabled option now only enables the metrics for Keycloak. To enable the readiness and liveness probe, there’s the new build option health-enabled. This allows more fine-grained usage of these options.

The default Keycloak distribution is now based on Quarkus. The new distribution is faster, leaner, and a lot easier to configure!

We appreciate migrating from the WildFly distribution is not going to be straightforward for everyone, since how you start and configure Keycloak has radically changed. With that in mind we will continue to support the WildFly distribution until June 2022.

For information on how to migrate to the new distribution check out the Quarkus Migration Guide.

A lot of effort went into polishing and improving the Quarkus distribution to make it as good as an experience as possible. A few highlights include:

Keycloak server was upgraded to use Wildfly 26.0.0.Final as the underlying container.

For more information on WildFly 26 refer to the WildFly 26 release notes.

Keycloak server was upgraded to use Wildfly 25.0.1.Final as the underlying container.

WildFly 25 drops support for the legacy security subsystem, which is being replaced fully by Elytron. This requires significant changes to how Keycloak is configured. Please, refer to the migration guide for more details.

For more information on WildFly 25 refer to the WildFly 25 release notes.

Keycloak.X Quarkus preview distribution was upgraded to Quarkus 2.5.3.

Without comparison the biggest highlight of this release is all the improvements that have been made to the Quarkus distribution. So many in fact, that it will be hard to list them all.

The CLI has been polished to hell and back, and we believe it now provides a very simple and convenient approach to configuring and running Keycloak. It’s almost so simple that documentation shouldn’t be needed.

To get started, just unpack the distribution, then type bin/kc.[sh|bat] -h to discover awesomeness!

That doesn’t mean we don’t plan to provide documentation for configuring Keycloak, but it didn’t quite make it this time around. In lack of documentation expect a blog post to follow the release introducing all the changes to the Quarkus distribution, as well as an overview on how to use it.

We are rapidly moving towards making the Quarkus distribution our default distribution, and will soon deprecate the WildFly distribution. With this in mind it is important that as many people as possible give it a test-run and provide us with feedback if you find any usability issues, are not able to configure something with it, or if you discover any bugs.

We’d love to hear your thoughts and get your feedback in GitHub Discussions!

The new admin console is shaping up really nicely, and a preview is included in the main distribution. It is not quite feature complete yet, but there are still loads of things to try out.

Upgrading from WildFly 23 to WildFly 25 has taken a lot longer than we would have liked. We’re still working hard on this and are hoping to release Keycloak 16 as soon as possible with the upgrade, but as we wanted to get the updates to the Quarkus distribution out there we are doing this release in the meantime.

In WildFly 25 there is now excellent native OpenID Connect support without the need for the Keycloak adapter. With this in mind we are deprecating our WildFly adapter and will not support WildFly 25, but it will be around for a while for older WildFly versions and Red Hat JBoss Enterprise Application Platform 7.y.

A long time ago, with Spring Security 5.0, there is now native support for OAuth 2.0 and OpenID Connect in Spring. With this in mind now is the time to start deprecating our Spring Boot and Security adapters.

Keycloak now supports OpenID Connect Front-Channel Logout 1.0.

For more details, take a look at Server Administration Guide.

Thanks to Ronaldo Yamada for the contribution.

With this release, we have deprecated and/or marked as unsupported some features in the Keycloak Operator. This concerns the Backup CRD and the operator managed Postgres Database.

The Keycloak server has improved support for the Financial-grade API (FAPI). More specifically, Keycloak is now compliant with FAPI CIBA and with OpenBanking Brasil. We also have support for CIBA ping mode. Thanks to Takashi Norimatsu, who did most of the work on FAPI CIBA and who is continually doing a really awesome job for the Keycloak project. Also thanks to Dmytro Mishchuk, Andrii Murashkin, Hryhorii Hevorkian and Leandro José de Bortoli, who did a great deal of the work on the FAPI compliance as well. Finally thanks to all the members of the FAPI Special interest group for their help and feedback.

The Keycloak server has now official support for client policies and Financial-grade API (FAPI). This capability was previewed in earlier versions, but now it is more polished and properly documented. Thanks to Takashi Norimatsu, who did most of the work on this. Also thanks to Dmytro Mishchuk, Andrii Murashkin and Hryhorii Hevorkian, who did a great deal of the work on this feature as well. Finally thanks to all the members of the FAPI Special interest group for their help and feedback.

In this version, there were several improvements to the User Profile SPI in order to prepare the ground on how users profiles are managed in Keycloak.

One of these improvements is the support for configuring user profiles through the administration console. For more details proceed to Server Administration Guide

Thanks to the community and all the individuals involved in this effort.

Offline session preloading has been improved and should be faster thanks to Peter Flintholm.

As a preview feature, offline session preloading can be skipped in favor of lazy loading thanks to Thomas Darimont's efforts. This feature has to be explicitly activated in the server configuration, see Server administration guide for details.

The Keycloak server was upgraded to use Wildfly 23.0.2.Final as the underlying container.

Support for OAuth 2.0 Device Authorization Grant is now available.

Thanks to Hiroyuki Wada, Łukasz Dywicki and Michito Okai.

Support for OpenID Connect Client Initiated Backchannel Authentication (CIBA) is now available.

Thanks to Takashi Norimatsu, Andrii Murashkin, Christophe Lannoy and members of the FAPI WG for the implementation and feedback.

Keycloak now supports communication with clients using SAML Artifact binding. A new Force Artifact Binding option was introduced in the client configuration, that forces communication with the client using artifact messages. For more details proceed to Server Administration Guide. Please note, that with this version, Keycloak SAML client adapter does NOT support Artifact binding.

Thanks to AlistairDoswald and harture.

Keycloak can now leverage PKCE when brokering to an external OpenID Connect IdP.

Thanks to thomasdarimont.

Default roles are now internally stored as composite roles of a new role usually named default-roles-<realmName>. Instead of assigning both realm and all client default roles directly to newly created users or users imported through Identity Brokering, just the role is assigned to them and the rest of default roles are assigned as effective roles. This change improves performance of default roles processing, especially with larger number of clients, because it is no longer necessary to go through all clients.

Introduction a preview of the new and upcoming Keycloak.X distribution. This distribution is powered by Quarkus, bringing significant improvements to startup time and memory consumption, as well as making it a lot easier to configure Keycloak.

The new account console is no longer a preview feature and is now the default account console in Keycloak. The old account console will stay around for a while. For those that have a custom theme for the old account console the old console will be used by default, giving you the time to update your custom theme to the new account console.

Support for OpenID Connect Back-Channel Logout is now available, thanks to DaSmoo and benjamin37.

The Keycloak server was upgraded to use Wildfly 21 as the underlying container.

Support for specification of AuthnContext section in authentication requests issued by SAML identity provider has been added.

Thanks to lscorcia

There was lots of the work done to have support for Financial-grade API Read and Write API Security Profile (FAPI RW). This is available with the usage of Client policies and it is still in the preview state. You can expect more polishing in the next releases. Thanks to Takashi Norimatsu and all the members of the FAPI Special interest group.

The Keycloak login theme components have been upgraded to PatternFly 4. The old PatternFly 3 runs simultaneously with the new one, so it’s possible to have PF3 components there.

There are also design changes in the login theme for better user experience. You can even define an icon for your custom Identity providers. For details, please refer to the docs.

Gatekeeper reached end of life, in November 21. This means that we no longer support, or update it. The announcement is available here.

Support for LDAPv3 password modify operation was added. Also the ability in the admin console to request metadata from the configured LDAP server to see if it supports LDAPv3 password modify operation.

Thanks to cachescrubber

Namespace support for LDAP group mapper allows you to map groups from LDAP under specified branch (namespace) of the Keycloak groups tree. Previously groups from LDAP were always added as the top level groups in Keycloak.

Thanks to Torsten Juergeleit

Keycloak server was upgraded to use WildFly 20.0.1.Final under the covers. For more details, please take a look at Upgrading Guide.

The SameSite value None for JSESSIONID cookie is necessary for correct behavior of the Keycloak SAML adapter. Usage of a different value is causing resetting of the container’s session with each request to Keycloak, when the SAML POST binging is used. Refer to the following steps for Wildfly and Tomcat to keep the correct behavior. Notice, that this workaround should be working also with the previous versions of the adapter.

With Identity Brokering Sync Mode it is now possible to control if user profiles are updated on first login, or every login from an external Identity Provider. It is also possible to override this behaviour on individual mappers.

Thanks to Martin Idel

Typically, an SSO session last for days if not months, while individual client sessions should ideally be a lot shorter. With the introduction of client session timeout it is now possible to configure a separate timeout for individual clients, as well as a default for all clients within a realm.

Thanks to Yoshiyuki Tabata

For applications that use Keycloak as an OAuth 2.0 Authorization Server there is now support to revoke refresh tokens through the token revocation endpoint.

Thanks to Yoshiyuki Tabata

A new SPI was introduced to allow better flexibility when setting security related headers on responses. This provides a cleaner implementation within Keycloak, but also allows full customisation if needed. Security headers are now set by a response filter instead of within the code itself, which makes it less error-prone, removing the chance that some response are missing headers.

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

The promiseType init option has been removed from the JavaScript adapter. Instead a promise that supports both native promise API and legacy Keycloak promise API is returned. This allows gradually migration of applications from the legacy/deprecated API to the native promise API.

In 9.0.0 a breaking API change was introduced to LocaleSelectorSPI. With 9.0.1 the changes to this API is now reverted, and a new LocaleUpdaterSPI has been introduced.

In previous releases, Spring Boot applications had to manually implement the KeycloakConfigResolver interface or extend the built-in org.keycloak.adapters.springboot.KeycloakSpringBootConfigResolver.

This release fixes the backward compatibility issue by resolving instances automatically in case none is provided. As well as still allowing applications to provide their own configuration resolver implementations.

The Drools Policy was finally removed after the deprecation period. If you need more complex policies you can still use JavaScript-based policies.

Pagination support was added to clients in the Admin Console and REST API. Thanks to saibot94.

A new built-in vault provider that reads secrets from a keystore-backed Elytron credential store has been added as a WildFly extension. The creation and management of the credential store is handled by Elytron using either the elytron subsystem or the elytron-tool.sh script.

In this release, we did some usability improvements to the authentication flows. It should be easier for the end user to choose between available authentication mechanisms for two-factor authentication. It should be more intuitive to log in with OTP or WebAuthn considering the fact that user can have more OTP or WebAuthn credentials. There is also better support for passwordless WebAuthn authentication. Finally, we did some work on defects related to the authentication flows.

A number of improvements have been made to how the locale for the login page is selected, as well as when the locale is updated for a user.

Starting with version 80, Google Chrome will change the default value for the SameSite cookie parameter to Lax. Therefore, changes were required to several Keycloak cookies (especially those which are used within the Javascript adapter for checking the session status using the iframe) to set SameSite parameter to None. Please note that this setting also requires setting the Secure parameter, hence starting with this version, the Javascript adapter will only be fully functional when using the SSL / TLS connection on the Keycloak side.

This release fixes a critical vulnerability in LDAP introduced in Keycloak 7. If you are using Keycloak 7.0.0, 7.0.1 or 8.0.0 in production we strongly suggest that you upgrade immediately.

Upgrade to WildFly 18.0.1.Final which includes updates to a number of CVEs in third-party libraries.

Several configuration fields can obtain their value from a vault instead of entering the value directly: LDAP bind password, SMTP password, and identity provider secrets.

Furthermore, new vault SPI has been introduced to enable development of extensions to access secrets from custom vaults.

The fixed and request hostname providers have been replaced with a single new default hostname provider. This provider comes with a number of improvements, including:

Message bundles in theme resources enables internationalization of custom providers such as authenticators. They are also shared between all theme types, making it possible to for example share messages between the login and account console. Thanks to micedre.

We have added a new SPI that allows for the configuration of custom role mappers that are used by the SAML adapters to map the roles extracted from the SAML assertion into roles that exist in the SP application environment. This is particularly useful when the adapters need to communicate with third party IDPs and the roles set by the IDP in the assertion do not correspond to the roles that were defined for the SP application. The provider to be used can be configured in the keycloak-saml.xml file or in the keycloak-saml subsystem. An implementation that performs the role mappings based on the contents of a properties file was also provided.

Notice that when Keycloak acts as the IDP we can use the built-in role mappers to perform any necessary mappings before setting the roles into the assertion, so this SPI will probably be redundant in this case. The RoleMappingsProvider SPI was designed for situations when the IDP offer no way to map roles before adding them to the assertion.

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

In this release, we added initial support for W3C Web Authentication (WebAuthn). There are a few limitations in current implementation, however we are working on further improvements in this area. Thanks to tnorimat for the contribution. Also thanks to ynojima for the help and feedback.

With the arrival of W3C Web Authentication support, we’ve refined the authentication flow system to be able to allow a user to select which authentication method is preferred for login (for example, the choice between an OTP credential and a WebAuthn credential). The new mechanisms also allow an administrator to craft flows for password-less login, for example just using WebAuthn as an authentication method. Please note that with these changes, any custom authentication flow you have created may need to be adapted to the new flow logic.

As a result of these changes, users can now have multiple OTP devices and multiple WebAuthn devices. The same system that allows a user to select which type of device to use during login also allows that user to select which specific device to use. Thanks to the Cloudtrust team: AlistairDoswald, sispeo and Fratt for their contributions, and to harture and Laurent for their help.

It is now possible to use system properties and environment variables within theme.properties file. Thanks to Opa-

Thanks to tnorimat, we support more signing algorithms for client authentication with signed JWT.

In this release, possibility to authenticate OIDC providers with signed JWT or basic authentication was added. So all the client authentication methods mentioned in the OIDC specification are supported now. Thanks to madgaet and rradillen for contributions.

Thanks to jonkoops now it’s possible to enable or disable logging for the JS adapter.

The option to provide client credentials in the JavaScript adapter was removed. Thanks to jonkoops

Please take a look at 7.0.1 Release Notes for more details on how you can now deploy and run scripts to customize specific behavior.

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

Java adapter for Apache Tomcat 8 and Apache Tomcat 9 was unified and now it serves for both of them.

A lot of work has been done on the new Account Console and Account REST API. It’s not quite ready yet, but it’s getting there and hopefully will be fully done for Keycloak 8.

Keycloak can support the signed and encrypted ID token according to the Json Web Encryption (JWE) specification. Thanks to tnorimat.

The Keycloak team has spent a significant amount of time on automation around testing and releases both for Keycloak and Red Hat Single Sign-On.

Keycloak now comes enabled with the SmallRye Health and Metrics extensions which provides standard health and metrics endpoints. We will add some documentation as well as Keycloak specific metrics soon.

UMA 2.0 is now supported for Authorization Services. Check the documentation for more details if you are coming from previous versions of Keycloak.

Clients applications are now able to send arbitrary claims to Keycloak along with an authorization request in order to evaluate permissions based on these claims. This is a very handy addition when access should be granted (or denied) in the scope of a specific transaction or based on information about the runtime.

It is now possible to associated attributes with resources protected by Keycloak and use these same attributes to evaluate permissions from your policies.

In some situations, you may want to just send regular access tokens to a resource server but still be able to enforce policies on these resources.

One of the main changes introduced by this release is that you are no longer required to exchange access tokens with RPTs in order to access resources protected by a resource server (when not using UMA). Depending on how the policy enforcer is configured on the resource server side, you can just send regular access tokens as a bearer token and permissions will still be enforced.

Until now, when deploying an application configured with a policy-enforcer, the policy enforcer would either load all protected paths from the server or just map these paths from the adapter configuration. Users can now decide to load paths on-demand from the server and avoid map these resources in the adapter configuration. Depending on how many protected resources you have this functionality can also improve the time to deploy an application.

In order to avoid unnecessary hits to the server, the policy enforcer caches the mapping between protected resources and their corresponding paths in your application. Users can now configure the behaviour of the cache or even completely disable it.

The policy-enforcer definition on the adapters (keycloak.json) was also updated to support the concept of pushed claims. There you have the concept of a claim-information-point which can be set to push claims from different sources such as the HTTP request or even from an external HTTP service.

The Evaluation API used to implement policies in Keycloak, especially JavaScript and Drools policies, provides now methods to:

UMA 2.0 is now supported for Authorization Services, including support for users to manage user access through the account management console. There are also other additions and improvements to authorization services.

Clients can now push additional claims and have them used by policies when evaluating permissions.

It is now possible to define attributes on resources in order to have them used by policies when evaluating permissions.

We now have support for Spring Boot 2.

We now have support for Fuse 7.

The JavaScript adapter now supports native promises. It retains support for the old style promises as well. Both can be used interchangeably.

It is now possible to pass Cordova-specific options to login and other methods in the JavaScript adapter. Thanks to loorent for the contribution.