Keycloak 17.0.0 released

February 11 2022

To download the release go to Keycloak downloads.

Release notes

Highlights

Quarkus distribution is now fully supported

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.

Quarkus distribution updates

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:

  • A new approach to documentation in form of server guides to help you install and configure Keycloak

  • Upgraded Quarkus to 2.7.0.Final

  • Configuration file is no longer Java specific, and aligns configuration keys with CLI arguments

  • Clearer separation between build options and runtime configuration.

  • h2-mem and h2-file databases renamed to dev-mem and dev-file.

  • Simplified enabling and disabling features

  • Custom, and unsupported, Quarkus configuration is done through conf/quarkus.properties.

  • Ability to add custom Java Options via JAVA_OPTS_APPEND (thanks to dasniko)

  • Initial logging capabilities

  • Initial support for Cross-DC

  • User-defined profiles are no longer supported but using different configuration files to achieve the same goal

  • Quickstarts updated to use the new distribution == Other improvements

Offline sessions lazy loaded

The offline sessions are now lazily fetched from the database by default instead of preloading during the server startup. To change the default behavior, see Server Administration Guide.

Keycloak now supports a glob-like syntax for the user search when listing users in the Admin Console, which allows for three different types of searches: prefix (foo* which became the default search), infix (*foo*), and exact "foo")

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

Default distribution is now powered by Quarkus

The default distribution of Keycloak is now powered by Quarkus, which brings a number of breaking changes to you configure Keycloak and deploy custom providers. For more information check out the Quarkus Migration Guide.

The WildFly distribution of Keycloak is now deprecated, with support ending June 2022. We recommend migrating to the Quarkus distribution as soon as possible. However, if you need to remain on the legacy WildFly distribution for some time, there are some changes to consider:

  • Container images for the legacy distribution tags have changed. To use the legacy distribution use the tags legacy or 17.0.0-legacy.

  • Download on the website for the legacy distribution has changed to keycloak-legacy-17.0.0.[zip|tar.gz].

If you encounter problems migrating to the Quarkus distribution, missing ability to configure something, or have general ideas and feedback, please open a discussion in GitHub Discussions.

Migrating from the preview Quarkus distribution

A number of things have changed since the preview Quarkus distribution was released in Keycloak 15.1.0. The ideal way to learn about what’s changed is to check out the new Server guides. In summary, the changes include:

  • Container now published to quay.io/keycloak/keycloak:latest and quay.io/keycloak/keycloak:17.0.0

  • Download on website renamed to keycloak-17.0.0.[zip|tar.gz].

  • conf/keycloak.properties changed to conf/keycloak.conf, which unifies configuration keys between the config file and CLI arguments.

  • Clearer separation between build options and runtime configuration.

  • Custom Quarkus configuration is done through conf/quarkus.properties.

  • h2-mem and h2-file databases renamed to dev-mem and dev-file.

  • Features are now enabled/disabled with --features and --features-disabled replacing the previous approach that had an separate config key for each feature.

  • Runtime configuration can no longer be passed to kc.[sh|bat] build and is no longer persisted in the build

  • Logging level and format is now configured with --log-level and --log-format, while in the past these had to be configured using unsupported Quarkus properties.

Client Policies Migration : client-scopes

If you used a policy including client-scopes condition and edited JSON document directly, you will need to change the "scope" field name in a JSON document to "scopes".

Liquibase upgraded to version 4.6.2

Liquibase was updated from version 3.5.5 to 4.6.2, which includes, among other things, several bug fixes, and a new way of registering custom extensions using ServiceLoader.

Migration from previous Keycloak versions to Keycloak 17.0.0 has been extensively tested with all currently supported databases, but we would like to stress the importance of closely following the Upgrading Guide, specifically of backing up existing database before upgrade. While we did our best to test the consequences of the Liquibase upgrade, some installations could be using specific setup unknown to us.

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.