Keycloak 21.0.0 released

February 23 2023

To download the release go to Keycloak downloads.

Release notes

Old Admin Console removed

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 uses Micrometer for metrics

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.

Java 11 support for Keycloak server deprecated

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.

Hashicop Vault no longer supported

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

See this discussion for more details.

SAML SP metadata changes

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.

XML-Enc algorithm

Keycloak realm key algorithm





Deprecated methods from user session provider were removed

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.

New storage: IS_CLIENT_ROLE searchable field was deprecated

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 preview support

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.

Support for the standard Forwarded header when running behind a reverse proxy

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.

The container image is now based on ubi9-micro

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!

Other improvements

Migration from 21.0

Before you upgrade remember to backup your database. If you are not on the previous release refer to the documentation for a complete list of migration changes.

Keycloak uses Micrometer for metrics

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, which is the recommended metrics library for Quarkus.

Due to this change, metrics have been renamed. The following table shows some examples.

Before upgrading it is recommended to review all metrics returned from the endpoint before and after the change, and update their usage in dashboards and alerts.

Table 1. Examples of changed metrics names
Old metric name New metric name









Deprecated RSA_SHA1 and DSA_SHA1 algorithms for SAML

Algorithms RSA_SHA1 and DSA_SHA1, which can be configured as Signature algorithms on SAML adapters, clients and identity providers are deprecated. We recommend to use safer alternatives based on SHA256 or SHA512. Also, verifying signatures on signed SAML documents or assertions with these algorithms do not work on Java 17 or higher. If you use this algorithm and the other party consuming your SAML documents is running on Java 17 or higher, verifying signatures will not work.

The possible workaround is to remove algorithms such as or from the list of "disallowed algorithms" configured on property jdk.xml.dsig.secureValidationPolicy in the file $JAVA_HOME/conf/security/

SAML SP metadata changes

In this version, Keycloak will refuse to decrypt assertions encrypted using a realm key generated for signing purpose. This change means all encrypted communication from IDP to SP (where Keycloak acts as the SP) will stop working.

There are two ways to make this work:

  • either update the IDP configuration with the metadata generated by a newer version of Keycloak,

  • or run Keycloak in backward compatibility mode that will make Keycloak work with the metadata generated by older Keycloak versions. This mode can be enabled using -Dkeycloak.saml.deprecated.encryption=true flag. Note this backward compatibility mode is planned to be removed in Keycloak 24.

Deprecated methods from user session provider were removed

In Keycloak 13 there was introduced UserLoginFailureProvider and some methods from UserSessionProvider were moved there. The methods in UserSessionProvider were deprecated and now has been removed. Javadoc of these methods contained a corresponding replacement (see Javadoc of Keycloak 20 release).

Custom themes using old admin console won’t work

The old admin console, which was deprecated in previous versions, was finally removed. This also means that your custom themes, which were using it as parent theme or importing from it, won’t work. It is highly recommended to not deploy such themes at all as extending old admin console is not applicable anymore and there can be issues in Keycloak (at least warnings or errors in the logs) with such themes deployed.

Curl has been removed from the container

The Keycloak Container Image has been modified to enhance security. As a result, curl and other CLI tools have been removed, which you may have been using in your customized image. See the updated container guide for information on how to handle this change.

All resolved issues

New features




Before you upgrade remember to backup your database and check the upgrade guide for anything that may have changed.