Keycloak 20.0.0 released

November 01 2022

To download the release go to Keycloak downloads.

Release notes

WildFly distribution removed

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.

New Keycloak Operator upgrade

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.

Realm Operator

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.

Supported OpenJDK versions

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.

Hostname provider now supports configuring the complete base URL

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

  • hostname-url

  • hostname-admin-url

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

Improvements to kc.bat when running Keycloak on Windows

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

Upgrade of embedded H2 database

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.

Feature guard for hosting the Keycloak JavaScript adapter

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.

OTP Application SPI

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.

Custom Identity Providers can now set an icon for the provider

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.

FIPS 140-2 experimental support

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.

Search groups by attribute

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

View group membership in the account console

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

Deprecated methods from data providers and models were removed

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.

Migration from 19.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.

RESTEasy Version Update

Updated the RESTEasy version of Keycloak Admin REST Client to the next major version.

H2 Version Update

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. This change might require changes to the H2 JDBC URL or migration of the H2 database files in an existing Keycloak setup.

Changes to the H2 JDBC URL

For Keycloak to run with its JPA legacy store with H2 version 2.x, the JDBC URL requires the attribute NON_KEYWORDS=VALUE.

In a setup where H2 is initialized by Keycloak without extra parameters, Keycloak will append the attribute automatically. This is the default for development setups.

If an H2 JDBC URL is provided on the command line or in a configuration file, and it already contains the NON_KEYWORDS= attribute in the JDBC URL, this attribute needs to be amended with the VALUE keyword.

If the connection factory for the H2 database is initialized outside Keycloak, that initialization needs to take care of adding the NON_KEYWORDS attribute.

See the H2 documentation on the NON_KEYWORDS attribute for details.

Upgrade of H2 database files

H2 database base files created with H2 version 1.x should not be used with version 2.x.

Purge existing H2 database files to start with an empty database, export and import the realms using Keycloak’s export and import functionality, or refer to the migration notes on the H2 database project’s website for details on how to migrate H2 database contents.

Breaking changes in the new version of Keycloak Operator

Note
In order to use the newest version of the Keycloak Operator, the manual reinstallation and upgrade of your CRs are required. There’s no automated migration.

This release contains the following breaking changes in Keycloak CRs:

serverConfiguration free-form field was renamed

From now on it’s called additionalOptions. The idea behind this decision is to align it more with the Keycloak Quarkus distribution and achieve/preserve a naming consistency. serverConfiguration can be still used for configuring options that haven’t got a declared alternative in Keycloak custom resources (CRs). A good example of such use can be service providers.

Ingress options were refined

In the past, it used to be defined via the disableDefaultIngress property. We decided to clarify it a bit, thus from now on you can use the following structure to control your ingress settings:

spec:
    ...
    ingress:
      enabled: false

HTTP options were added

Similarly, like with ingress, you can define multiple HTTP options in a better structural manner:

spec:
    ...
  http:
    httpEnabled: true
    httpPort: 80
    httpsPort: 443
    tlsSecret: my-tls-secret

Hostname options were added

Last but not least, the hostname options were also changed:

spec:
    ...
  hostname:
    hostname: [keycloak-server-hostname]
    admin: [admin-console-hostname]
    adminUrl: [admin-console-base-url]
    strict: [true|false]
    strictBackchannel: [true|false]

Some fields are no longer required

The hostname and tlsSecret fields are now optional to align with the Quarkus distribution configuration. With that we also removed the possibility to set INSECURE-DISABLE special value to those fields. In order to disable hostname checks and enable HTTP, please follow the same approach as with the Quarkus distribution, i.e. set strict: false, strictBackchannel: false and httpEnabled: true fields.

OLM channel was changed to fast

The default channel of Keycloak Operator Lifecycle Manager was changed to fast.

Deprecated methods from data providers and models were removed

Prior to Keycloak 15, there was a clean-up of provider and model interfaces where we deprecated some methods. Javadoc of these methods contained a corresponding replacement method (see Javadoc of Keycloak 19 release). In this release the methods were removed. The following is a list of all changed classes.

The most common patterns for deprecating and removing the methods are the following.

  • Streamification - interfaces now contain only Stream-based methods.

    For example in GroupProvider interface

    @Deprecated
    List<GroupModel> getGroups(RealmModel realm);

    was replaced by

    Stream<GroupModel> getGroupsStream(RealmModel realm);

    More details on streamification work can be found in KEYCLOAK-14011.

  • Consistent parameter ordering - methods now have strict parameter ordering where RealmModel is always the first parameter.

    For example in UserLookupProvider interface

    @Deprecated
    UserModel getUserById(String id, RealmModel realm);

    was replaced by

    UserModel getUserById(RealmModel realm, String id)

List of changed interfaces

(o.k. stands for org.keycloak. package)

  • server-spi module

    • o.k.credential.CredentialInputUpdater

    • o.k.credential.UserCredentialStore

    • o.k.models.ClientProvider

    • o.k.models.ClientSessionContext

    • o.k.models.GroupModel

    • o.k.models.GroupProvider

    • o.k.models.KeyManager

    • o.k.models.KeycloakSessionFactory

    • o.k.models.ProtocolMapperContainerModel

    • o.k.models.RealmModel

    • o.k.models.RealmProvider

    • o.k.models.RoleContainerModel

    • o.k.models.RoleMapperModel

    • o.k.models.RoleModel

    • o.k.models.RoleProvider

    • o.k.models.ScopeContainerModel

    • o.k.models.UserCredentialManager

    • o.k.models.UserModel

    • o.k.models.UserProvider

    • o.k.models.UserSessionProvider

    • o.k.models.utils.RoleUtils

    • o.k.sessions.AuthenticationSessionProvider

    • o.k.storage.client.ClientLookupProvider

    • o.k.storage.group.GroupLookupProvider

    • o.k.storage.user.UserLookupProvider

    • o.k.storage.user.UserQueryProvider

  • server-spi-private module

    • o.k.events.EventQuery

    • o.k.events.admin.AdminEventQuery

    • o.k.keys.KeyProvider

All changes are linked to the following issue.

All resolved issues

New features

Enhancements

Bugs

Upgrading

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