Keycloak 17.0.0 released. Now based on Quarkus

February 11 2022

To download the release go to Keycloak downloads.

Featured Content Ads

add advertising here

COGNAC Metaverse

Explore World's first metaverse that is as real as our Real world.

https://cognac.knowasiak.com

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 migration/migrating-to-quarkus[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:

Featured Content Ads

add advertising here

COGNAC Metaverse

Explore World's first metaverse that is as real as our Real world.

https://cognac.knowasiak.com

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 on longer Java specific, and aligns configuration keys with CLI arguments
Clearer separation between build options and runtime configuration.
Featured Content Ads
add advertising here
Your AI Companion only on new Bing.
Join the new internet where you get what you ask, Fast and precise.
https://www.bing.com
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.

Improved User Search

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 16.1

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 migration/migrating-to-quarkus[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

#8979 Convert MapUserEntity to interface keycloak storage
#9170 Create Operator.X module in repo keycloak operator
#9171 Keycloak.X deployment keycloak operator
#9172 Realm CRD keycloak operator
#9174 Testsuite baseline keycloak operator
#9222 Let users configure Dynamic Client Scopes keycloak
#9223 Create an internal representation of RAR that also handles Static and Dynamic Client Scopes keycloak
#9224 Handle Dynamic Scopes correctly in the consent screen keycloak
#9532 Publish ECMAScript Modules for keycloak-js keycloak adapter/javascript
#9567 Package server guides to be used in the website keycloak dist/quarkus
#9663 JPA map storage: Client scope no-downtime store keycloak storage
#9740 Convert authorization services entities into interface keycloak storage
#9787 Generate the CRD from RealmRepresentation keycloak operator
#9803 Improve user search query keycloak storage
#10077 Configurable session limits keycloak authentication

Enhancements

#285 Update Kubernetes and OpenShift examples used by getting started guides to use Quarkus dist keycloak-quickstarts
#286 Update getting-started in QuickStarts to use Quarkus dist keycloak-quickstarts
#370 Update default container to Quarkus keycloak-containers
#1388 Update documentation for Quarkus distribution keycloak-documentation
#1392 Release notes for Keycloak 17 keycloak-documentation
#1393 Migration from Keycloak.X preview keycloak-documentation
#9034 Documentation for Quarkus distribution keycloak dist/quarkus
#9135 Disable pre-loading offline sessions by default keycloak dist/quarkus
#9144 Remove Hashicorp Support keycloak dist/quarkus
#9165 Make JsonbType generic keycloak storage
#9175 Tree storage: introduce notion of per-field primary and cached status in an entity keycloak storage
#9206 Provide documentation for proxy mode in Quarkus based Keycloak keycloak dist/quarkus
#9216 Review README files. keycloak dist/quarkus
#9240 Add indexing to HotRodGroupEntity keycloak storage
#9244 Make JpaClientStorage* classes generic keycloak storage
#9259 Refactor generated constructors in new store entities keycloak storage
#9262 Avoid building configuration all the time when running tests keycloak
#9284 Remove override on xmlsec in quarkus/pom.xml keycloak dist/quarkus
#9293 Database configuration tests keycloak
#9332 Upgrade Infinispan to 12.1.7.Final keycloak storage
#9409 Cross-site validation for lazy loading of offline sessions keycloak storage
#9410 Switch default offline sessions to lazy loaded keycloak docs
#9427 HotRod map storage uses regex pattern that could be precompiled keycloak storage
#9452 Add configuration guide keycloak dist/quarkus
#9469 Validation for CIBA binding_message parameter keycloak
#9476 Upgrade Liquibase to 4.6.2 keycloak storage
#9494 Add more details about 2FA to authenticate page keycloak
#9504 Verify the WebAuthn functionality and settings for authentication keycloak testsuite
#9530 Enable only TLSv1.3 as default for the https protocol and set expected values keycloak dist/quarkus
#9537 Backward compatibility for lower-case bearer type in token responses keycloak
#9544 Test scenarios for verifying of JS injection for WebAuthn Policy keycloak testsuite
#9547 Improve the kustomize setup for the operator keycloak operator
#9552 Readiness and Liveness probe for the operator deployment of Keycloak.X keycloak operator
#9555 Multiple warnings caused by typed varargs in TokenVerifier keycloak
#9570 optimize title/summary and headlines for proxy guide keycloak dist/quarkus
#9575 Add support to linking between guides keycloak docs
#9614 Remove output of summary in guides keycloak docs
#9618 Build command should only accept built-time options keycloak dist/quarkus
#9631 Exclude some folders from our SAST analysis keycloak
#9657 Convert MapClientScopeEntity to interface keycloak storage
#9682 Add a quarkus.properties for unsupported configuration options keycloak dist/quarkus
#9683 Remove any reference to configuration profile keycloak dist/quarkus
#9687 Remove system property from help message keycloak dist/quarkus
#9688 Hide Hasicorp Vault from CLI keycloak dist/quarkus
#9706 Improve enabling/disabling features in Quarkus distribution keycloak dist/quarkus
#9710 Device Authorization Grant with PKCE keycloak
#9714 Adpaters for Map Storage swallow multi-valued attribute while Keycloak Core doesn’t support them keycloak storage
#9750 Restrict Dynamic Scopes to optional Client Scopes keycloak
#9751 Add section recommended exposed paths to reverse proxy documentation keycloak docs
#9788 Combine package files for JS adapter keycloak adapter/javascript
#9795 Add test scenarios for Passwordless Webauthn AIA keycloak testsuite
#9796 Extend and fix tests for Resident Keys for WebAuthn keycloak testsuite
#9800 Store information about transport media of WebAuthn authenticator keycloak authentication/webauthn
#9812 Sort options in guides by key keycloak docs
#9837 Update default ZIP distribution to Quarkus keycloak dist/wildfly
#9850 Complete support for Passwordless tests keycloak testsuite
#9858 Use keycloak.v2 admin theme by default if admin2 is enabled keycloak admin/ui
#9872 Quarkus update to 2.7.0 Final keycloak dist/quarkus
#9901 Initial logging support keycloak dist/quarkus
#9912 Add support for pinning guides to the top keycloak docs
#9919 Implement the Dynamic Scopes parsing for the resource-owner-password-credentials grant. keycloak oidc
#9996 Verify if enabling authentication and encryption for JGroups work on Quarkus dist keycloak dist/quarkus
#9999 Add note about escaping of vaules for config keycloak dist/quarkus
#10001 Logging guide for Quarkus dist keycloak dist/quarkus
#10029 Update com.github.ua-parser:uap-java to 1.5.2 keycloak dependencies
#10034 Remove external Collection utility class for WebAuthn keycloak authentication/webauthn
#10041 Cover enabling mtls in TLS guide keycloak dist/quarkus
#10060 Updated use of generics in JPA Map Storage keycloak storage
#10071 Create common parent for Jpa*AttributeEntity keycloak storage
#10073 Reduce Keycloak.x image size keycloak dist/quarkus

Bugs

#307 Incorrect dependency in package.json keycloak-nodejs-connect
#8727 KeycloakAuthenticatorValve (Tomcat) does not implement createRequestAuthenticator() keycloak adapter/jee
#9213 Spurious logs are spilling in Quarkus Distribution.X integration tests keycloak dist/quarkus
#9265 The title of the login screen is not translated into Japanese keycloak
#9324 Quarkus relational database setup documentation error keycloak
#9340 “look-ahead window” of TOTP should be “look around window” keycloak
#9371 Expected Scopes of ClientScopesCondition created on Admin UI are not saved onto ClientScopesCondition.Configuration keycloak authorization-services
#9382 Password credential decoding from DB may fail in rare cases – No login possible keycloak
#9397 Dist.X cannot connect to external Postgres if the password ends with an = sign keycloak
#9398 Dist.X apparently doesn’t apply correctly the db schema keycloak
#9411 JPA-Map storage might loose writes due to missing locking mechanism keycloak storage
#9421 Multiple active tabs when realm name equals name of tab in Admin console keycloak admin/ui
#9424 Missing german translation for webauthn-doAuthenticate keycloak translations
#9426 Hard coded message within account console v2 keycloak account/ui
#9447 Client Policies : Condition’s negative logic configuration is not shown in Admin Console’s form view keycloak
#9473 Placeholders in keycloak.properties do not get substituted at runtime after a build keycloak
#9479 Keycloak Server throws NPE at startup when the MAP_STORAGE feature is enabled keycloak storage
#9488 Setting “24 mins” to timeout, the admin console displays “1 day” keycloak admin/ui
#9498 Username editable when user is forced to re-authenticate keycloak authentication
#9501 Quarkus dist “providers” dir has outdated README keycloak dist/quarkus
#9503 Newline in localization messages causes uncaught syntax error in account console v2 keycloak account/ui
#9519 Dist.X argument parsing fails on semicolon keycloak dist/quarkus
#9529 KEYCLOAK-19289 check if values to set is not null keycloak
#9560 LDAP connection timeout is treated as login failure and brute force locking the user keycloak
#9585 Different method getGroupsCountByNameContaining in MapGroupProvider and JpaRealmProvider keycloak storage
#9587 MapRoleProvider could return also client roles when searching for realm roles keycloak storage
#9610 Missing DB constraints for JPA Map Storage for Clients keycloak storage
#9617 Scope bug in device authorization request keycloak
#9645 Handling lazy loading exceptions for storage in new and old storage keycloak storage
#9648 Model tests consistently time out keycloak storage
#9653 Keycloak.X cannot lookup embedded theme-resources from extension jars keycloak dist/quarkus
#9691 WebAuthnSigningInTest failures in pipeline keycloak testsuite
#9696 GHA failing due to wrong scheme when downloading ISPN server keycloak
#9705 Fixes for token revocation keycloak oidc
#9716 JPA Map storage doesn’t downgrade entityVersion when modifying a row written with a future entityVersion keycloak storage
#9774 Updated flag disappearing for nested entities in HotRod store keycloak storage
#9790 Build command exits with success with invalid arguments keycloak dist/quarkus
#9804 Review guides to use the correct format for options keycloak docs
#9807 Mapped Quarkus properties should not be persisted keycloak dist/quarkus
#9867 Unstable model tests when starting multiple Infinispan instances keycloak storage
#9874 JPA Map storage doesn’t increment version column on attribute update keycloak storage
#9892 Update Portuguese (Brazil) translations keycloak translations
#9906 Do not run re-augmentation if config is the same in dev mode keycloak dist/quarkus
#9956 Errors from CLI are masked by help keycloak dist/quarkus
#9973 Rename h2-file/h2-mem to dev-file/dev-mem and remove default values for username/password keycloak dist/quarkus
#10010 Keycloak is not capturing proper Signing details(like browser name and version) when logged in from different browsers keycloak account/ui
#10020 Not possible to register webauthn key on Firefox keycloak authentication/webauthn
#10033 JPA Map storage listener should handle optimistic locking for deleting entities keycloak storage
#10046 Failing to use cache remote-stores due to missing dependencies keycloak dist/quarkus
#10052 Can not set a jgroups stack other than the defaults from Infinispan keycloak dist/quarkus
#10067 JPA delegates can throw NoResultException when entity doesn’t have any attributes keycloak storage

Upgrading

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

Knowasiak