Repository navigation
Releases
25.0.1
Upgrading
Before upgrading refer to the migration guide for a complete list of changes.
All resolved issues
Enhancements
- #19750 Use a proper FreeMarker template for the new consoles
account/ui - #30346 Enhance masking around config-keystore
dist/quarkus
Bugs
- #25234 front channel logout to clients are not called at Identity Proxy when using front channel logout to Identity Provider(
oidc - #28643 Encountering `NullPointerException` - `KeycloakIdentity.getUserFromToken()` when running `admin-ui` locally
admin/ui - #30115 Admin v2 theme - theme.properties Custom theme scripts not loading
admin/ui - #30201 Keycloak CI - failure in Store IT (aurora-postgres)
ci - #30240 Custom attributes are removed during UPDATE PROFILE event
core - #30300 Upgrade to Keycloak 25 - Table 'USER_CONSENT' is specified twice on MySQL/MariaDB database
core - #30302 Methods of SimpleHttp are after change now too much protected
core - #30306 Upgrade to Keycloak 25 - Events bug in UI
admin/ui - #30332 Operator fails to patch ingress after update to 25.0.0
operator - #30334 RESTART_AUTHENTICATION_ERROR when login in in private browser window after 25.0.0 update
core - #30351 Migration of sessions in KC25 should run only on migration, not on imports
- #30368 Documentation : label error for persistent-user-sessions feature flag
docs - #30417 Keycloak 25 db guide shows unevaluated "ifeval
docs - #30432 keycloak hostname:v2 /admin used on "hostname" instead of "hostname-admin"
admin/ui - #30434 Improvements for ldap test authentication
ldap - #30492 partial_import_test fails randomly
admin/ui
25.0.0
Highlights
Account Console v2 theme removed
The Account Console v2 theme has been removed from Keycloak. This theme was deprecated in Keycloak 24 and replaced by the Account Console v3 theme. If you are still using this theme, you should migrate to the Account Console v3 theme.
Java 21 support
Keycloak now supports OpenJDK 21, as we want to stick to the latest LTS OpenJDK versions.
Java 17 support is deprecated
OpenJDK 17 support is deprecated in Keycloak, and will be removed in a following release in favor of OpenJDK 21.
Most of Java adapters removed
As stated in the release notes of previous Keycloak version, the most of Java adapters are now removed from the Keycloak codebase and downloads pages.
For OAuth 2.0/OIDC, this includes removal of the Tomcat adapter, WildFly/EAP adapter, Servlet Filter adapter, KeycloakInstalled desktop adapter, the jaxrs-oauth-client adapter, JAAS login modules, Spring adapter and SpringBoot adapters.
You can check our older post for the list of some alternatives.
For SAML, this includes removal of the Tomcat adapter and Servlet filter adapter. SAML adapters are still supported with WildFly and JBoss EAP.
The generic Authorization Client library is still supported, and we still plan to support it. It aims to be used in combination with any other OAuth 2.0 or OpenID Connect libraries. You can check the quickstar 8000 ts for some examples where this authorization client library is used together with the 3rd party Java adapters like Elytron OIDC or SpringBoot. You can check the quickstarts also for the example of SAML adapter used with WildFly.
Upgrade to PatternFly 5
In Keycloak 24, the Welcome page is updated to use PatternFly 5, the latest version of the design system that underpins the user interface of Keycloak. In this release, the Admin Console and Account Console are also updated to use PatternFly 5. If you want to extend and customize the Admin Console and Account Console, review the changes in PatternFly 5 and update your customizations accordingly.
Argon2 password hashing
Argon2 is now the default password hashing algorithm used by Keycloak in a non-FIPS environment.
Argon2 was the winner of the 2015 password hashing competition and is the recommended hashing algorithm by OWASP.
In Keycloak 24 the default hashing iterations for PBKDF2 were increased from 27.5K to 210K, resulting in a more than 10 times increase in the amount of CPU time required to generate a password hash. With Argon2 it is possible to achieve better security, with almost the same CPU time as previous releases of Keycloak. One downside is Argon2 requires more memory, which is a requirement to be resistant against GPU attacks. The defaults for Argon2 in Keycloak requires 7MB per-hashing request. To prevent excessive memory and CPU usage, the parallel computation of hashes by Argon2 is by default limited to the number of cores available to the JVM. To support the memory intensive nature of Argon2, we have updated the default GC from ParallelGC to G1GC for a better heap utilization.
New Hostname options
In response to the complexity and lack of intuitiveness experienced with previous hostname configuration settings, we are proud to introduce Hostname v2 options.
We have listened to your feedback, tackled the tricky issues, and created a smoother experience for managing hostname configuration. Be aware that even the behavior behind these options has changed and requires your attention - if you are dealing with custom hostname settings.
Hostname v2 options are supported by default, as the old hostname options are deprecated and will be removed in the following releases. You should migrate to them as soon as possible.
New options are activated by default, so Keycloak will not recognize the old ones.
For information on how to migrate, see the Upgrading Guide.
Persistent user sessions
Previous versions of Keycloak stored only offline user and offline client sessions in the databases.
The new feature persistent-user-session stores online user sessions and online client sessions not only in memory, but also in the database.
This will allow a user to stay logged in even if all instances of Keycloak are restarted or upgraded.
The feature is a preview feature and disabled by default. To use it, add the following to your build command:
bin/kc.sh build --features=persistent-user-session ...
For more details see the Enabling and disabling features guide. The sizing guide contains a new paragraph describing the updated resource requirements when this feature is enabled.
For information on how to upgrade, see the Upgrading Guide.
Cookies updates
SameSite attribute set for all cookies
The following cookies did not use to set the SameSite attribute, which in recent browser versions results in them
defaulting to SameSite=Lax:
-
KC_STATE_CHECKERnow setsSameSite=Strict -
KC_RESTARTnow setsSameSite=None -
KEYCLOAK_LOCALEnow setsSameSite=None -
KEYCLOAK_REMEMBER_MEnow setsSameSite=None
The default value SameSite=Lax causes issues with POST based bindings, mostly applicable to SAML, but also used in
some OpenID Connect / OAuth 2.0 flows.
Removing KC_AUTH_STATE cookie
The cookie KC_AUTH_STATE is removed and it is no longer set by the Keycloak server as this server no longer needs this cookie.
Deprecated cookie methods removed
The following APIs for setting custom cookies have been removed:
-
ServerCookie- replaced byNewCookie.Builder -
LocaleSelectorProvider.KEYCLOAK_LOCALE- replaced byCookieType.LOCALE -
HttpCookie- replaced byNewCookie.Builder -
HttpResponse.setCookieIfAbsent(HttpCookie cookie)- replaced byHttpResponse.setCookieIfAbsent(NewCookie cookie)
Addressed 'You are already logged in' for expired authentication sessions
The Keycloak 23 release provided improvements for when a user is authenticated in parallel in multiple browser tabs. However, this improvement did not address the case when an authentication session expired. Now for the case when user is already logged-in in one browser tab and an authentication session expired in other browser tabs, Keycloak is able to redirect back to the client application with an OIDC/SAML error, so the client application can immediately retry authentication, which should usually automatically log in the application because of the SSO session. For more details, see Server Administration Guide authentication sessions.
Lightweight access token to be even more lightweight
In previous releases, the support for lightweight access token was added. In this release, we managed to remove even more built-in claims from the lightweight access token. The claims are ad...
24.0.5
Highlights
Security issue with PAR clients using client_secret_post based authentication
This release contains the fix of the important security issue affecting some OIDC confidential clients using PAR (Pushed authorization request). In case you use OIDC confidential clients together
with PAR and you use client authentication based on client_id and client_secret sent as parameters in the HTTP request body (method client_secret_post specified in the OIDC specification), it is
highly encouraged to rotate the client secrets of your clients after upgrading to this version.
Upgrading
Before upgrading refer to the migration guide for a complete list of changes.
All resolved issues
Enhancements
- #29073 Use cache.compute() method to improve the replace retry loop
- #29280 Update Create Realm in Keycloak 24 Getting Started
Bugs
- #29129 JGroups creates log messages as it switched internally to "trace"
dist/quarkus - #29206 LDAP user creation reports error but user is created
ldap - #29314 Clicking the "save" button multiple times in the Saml IDP configuration page corrupts the value of "AuthnContext ClassRefs"
admin/ui - #29458 Empty CSP header value breaks security filter
authentication - #29471 Cypress tests store videos even for passing tests
ci - #29525 Maven clean build doesn't clean admin client generated files
ci - #29554 Cypress failing on video recording
ci - #29625 Database driver install examples can lead to permission errors in some circumstances
docs
24.0.4
Highlights
Partial update to user attributes when updating users through the Admin User API is no longer supported
When updating user attributes through the Admin User API, you cannot execute partial updates when updating the
user attributes, including the root attributes like username, email, firstName, and lastName.
For more details, see the Upgrading Guide.
Upgrading
Before upgrading refer to the migration guide for a complete list of changes.
All resolved issues
Enhancements
- #27508 Use new remote-store options in HA guides
- #28429 Add details to error 8000 messages, especially around refresh tokens
- #28729 Emphasize the need for setting container limit
docs - #28880 Upgrade to Quarkus 3.8.4
dist/quarkus - #29183 Minor corrections to High Availability Guide
docs
Bugs
- #16345 Unable to delete realm names with invalid URL characters
admin/api - #22617 kc export fails when using User Federation (LDAP) with file-based Vault enabled
import-export - #24568 iframe for frontend logout gets blocked if a custom CSP header is used
core - #24878 NoClassDefFoundError for Apache XML and EAP8
adapter/jee-saml - #27021 Workflow failure: Fuse adapter tests
ci - #27080 Workflow failure: Operator CI - KeycloakTruststoresTests#testTrustroreExists
ci - #27514 Uncaught server error: java.lang.IllegalArgumentException: Path parameter not provided
oidc - #28079 Group search does not work in user view
admin/ui - #28187 Admin UI drag & drop in flow config seems to delete actions
admin/ui - #28220 Admin API: User PUT operation clears firstname, lastname email fields
admin/api - #28303 WARN - Event object wasn't available in remote cache after event was received
infinispan - #28377 Broken lists in import/export server guide
docs - #28431 Dedicated client scopes always show up when searching
admin/ui - #28514 Message for searchClientRegistration is missing
admin/ui - #28666 Accessing a transient (lightweight) user through client session fails in admin-api/-ui
admin/ui - #28684 "Extend to children" button in authorization group policies is wrongly disabled
admin/ui - #28911 clients_saml_test.spec.ts fails in main
admin/ui - #29072 Startup probe should check for existence of an Admin user before returning 200
dist/quarkus - #29094 Fix the client name help grammatical error
admin/ui - #29133 DuplicateEmailValidator causes two DB queries on every login if a user has an email address
core - #29147 local user login not possible after LDAP connection problem
ldap - #29154 Update docs to distinguish between product names and CR names
docs - #29233 Broken link in documentation
docs
24.0.3
Upgrading
Before upgrading refer to the migration guide for a complete list of changes.
All resolved issues
Enhancements
- #26695 Keycloak and MSAD: enabling account in MSAD does not propagate to Keycloak
ldap
Bugs
- #24201 Cannot disable LDAP-backed user if importEnabled=false
ldap - #28100 Failed authentication: java.lang.NullPointerException: Cannot invoke "org.keycloak.models.UserModel.getFederationLink()" because "this.delegate" is null
identity-brokering - #28248 Update user makes User ID changes when federationLink and LDAP_ID is not set properly
admin/api - #28335 The false option of the pkceMethod init parameter for the JavaScript adapter is ignored
adapter/javascript - #28638 Missing permission to read configmaps in `keycloak-operator-role`
operator
24.0.2
Upgrading
Before upgrading refer to the migration guide for a complete list of changes.
All resolved issues
Enhancements
- #25057 Inconsistent behaviour on getting user permissions using authorization
authorization-services - #27433 Clarify format of keys in `additionalOptions` field in the Keycloak CR
docs - #27481 Edit High Availability guide
- #27484 Edit 23.0 changes part of Upgrading Guide
- #27632 Integrate downstream Upgrading Guide changes into upstream
- #27696 Upgrade to Quarkus 3.8.2
dist/quarkus - #27867 Corrections to Securing Apps Guide
- #27871 Upgrade to Infinispan 14.0.26
core - #27953 Address feedback to Keycloak Server guide
docs - #27955 Address term Keycloak in Server Administration Guide
docs - #28009 Address edits to the Operator Guide
- #28033 Upgrade Infinispan to 14.0.27.Final
- #28084 Upgrade to Quarkus 3.8.3
dist/quarkus
Bugs
- #14501 Getting failed to initialize js message if consent is rejected by user
account/ui - #15403 No email send on TOTP/Authenticator app removal
core - #20637 Reset password flow fails with "Page has expired" error when Kerberos authentication is enabled in the browser flow
authentication - #22644 Flaky test: org.keycloak.testsuite.forms.BrowserFlowTest#testAlternativeNonInteractiveExecutorInSubflow
core - #23701 Attribute search do
8000
es not work with federated users with ldap.
admin/ui - #23980 Keycloak Operator fails to install realm authentication flow because "flow is null"
import-export - #25490 Partial export/import is not mentioned in Keycloak's Server Administration Guide
docs - #25687 A java.lang.NullPointerException occurs when sending a Multipart/form-data request to any file upload interface.
admin/api - #26396 How do you update a custom user storage provider jar that includes a version number?
dist/quarkus - #27117 user sessions not accessible in all cluster nodes
infinispan - #27180 Grant type "urn:ietf:params:oauth:grant-type:uma-ticket" openid-connect/token service endpoint is returning refresh token with invalid Expiration
authorization-services - #27228 Lowercased "terms_and_conditions" is not migrated in fed_user_required_action table
core - #27245 Account console does not correctly treat link / unlink account
account/ui - #27269 mvnw clean install -Pdistribution on Windows deletes necessary files during clean of org.keycloak:keycloak-admin-ui
admin/ui - #27275 Invalidating offline token is not working from client sessions tab
authentication - #27366 Social login - test failures with unexpected status code
testsuite - #27483 Authz-client AuthorizationResource.getPermissions() ClassCastException
authorization-services - #27504 Cpu and memory sizing typo
docs - #27529 LegacyUserCredentialManager class not found
storage - #27540 URL change for liquibase docs
docs - #27548 Custom Browser Flow not working anymore
admin/ui - #27573 Release notes from 24.0.0 miss that multi-site active-passive deployments are supported
docs - #27597 dropping KC_PROXY=edge causes startup error
core - #27611 Cannot modify realm email settings since keycloak 24
user-profile - #27653 Admin tests: Flaky realm_settings_user_profile_enabled test
admin/ui - #27701 MTLS Cache options should be runtime options, not build time options
dist/quarkus - #27719 Wrong Welcome page image in the documentation
docs - #27745 Registration template in login2 is broken
login/ui - #27761 Snyk workflow failure
ci - #27779 Broken Migration "MigrateTo24_0_0"
core - #27780 Fixing downstream documentation build
docs - #27797 User profile fields cannot be set empty once they have a non-empty value (in Login Theme)
user-profile - #27820 Account console confusing with WebAuthn
account/ui - #27841 ES translation causes FreeMarker rendering issues
translations - #27852 VerifyUserProfile invalidates user cache on every login
core - #27878 Error when executing refresh grant, with scope param, without offline_access scope specified
oidc - #27882 Incorrect version of bctls-fips in the docs
docs - #27892 Truststore handling for the Operator is not documented
operator - #27894 Multi datasource configuration does not work in Keycloak 24.0.1
dist/quarkus - #27900 Performance impact in changed hashing measured wrong
authentication - #27925 Keycloak docs state that there are http metrics, but they are disabled
docs - #27954 Hibernate Dialect detection does not work anymore for Oracle DBs
storage - #27966 🍺 instead of dot: Attributes in account UI are not loaded
user-profile - #27967 ORA-01450 when updating keycloak 23 -> 24
storage - #27981 User Profile: Inconsistent ordering of attributes between account and login themes
user-profile - #28001 MySQL connector artifact should be ignored
dist/quarkus - #28012 Keycloak CR Truststore should not have a name
operator - #28113 We...
24.0.1
Highlights
Operator deploys nightly build instead of 24.0.0
Due to an issue in the release process when deploying Keycloak using the Operator it installed the nightly container
instead of 24.0.0.
As a quick fix to the issue, the 24.0.0 container was tagged with nightly, and the nightly releases was temporarily
disabled.
If you installed or upgraded to 24.0.0 using the Operator before 5pm CET yesterday the database may have been updated
with the wrong versions. To check if you are affected connect to your database and run the following SQL command:
SELECT * from migration_model WHERE version = '999.0.0';If the above returns a matching row you will need to take some actions, otherwise database migrations will not run for future releases. To resolve this run the following SQL command:
UPDATE migration_model SET version = '24.0.0' WHERE version = '999.0.0';Upgrading
Before upgrading refer to the migration guide for a complete list of changes.
24.0.0
Highlights
Supported user profile and progressive profiling
The user profile preview feature is promoted to be fully supported and user profile is enabled by default.
In the past months, the Keycloak team spent a huge amount of effort in polishing the user profile feature to make it fully supported. In this release, we continued the effort. Lots of improvements, fixes and polishing were done based on the thorough testing and feedback from our awesome community.
The following are a few highlights of this feature;
-
Fine-grained control over the attributes that users and administrators can manage so that you can prevent unexpected attributes and values from being set.
-
Ability to specify what user attributes are managed and should be displayed on the forms to regular users or administrators.
-
Dynamic forms - Previously, the forms where users created or updated their profiles, contain four basic attributes like username, email, first name and last name. The addition of any attributes (or removing some default attributes) required you to create a custom theme. Now custom themes may not be needed because users see exactly the requested attributes based on the requirement of the particular deployment.
-
Validations - Ability to specify validators for the user attributes including built-in validators that you can use to specify a maximum or minimum length, a specific regex, or limiting a particular attribute to be a URL or number.
-
Annotations - Ability to specify that particular attribute should be rendered for instance as a text area, an HTML select with specified options, or calendar or many other options. You can also bind JavaScript code to a specific field to change how an attribute is rendered and customize its behavior.
-
Progressive profiling - Ability to specify that some fields are required or available on the forms just for particular values of
scopeparameter. This effectively allow progressive profiling. You no longer need to ask the user for twenty attributes during registration; you can instead ask the user to fill in attributes incrementally according to the requirements of the individual client applications that are used by the user. -
Migration from previous versions - The user profile is now always enabled, but it operates as before for those who did not use this feature. You can benefit from the user profile capabilities, but you are not required to use them. For migration instructions, see the Upgrading Guide.
The first release of the user profile as a supported feature is just the starting point and the baseline for delivering many more capabilities around identity management.
We would like to give huge thanks to the awesome Keycloak community as lots of ideas, requirements and contributions came from the community! Special thanks to:
For more details about user profile capabilities, see the Server Administration Guide.
Breaking changes to the User Profile SPI
In this release, changes to the User Profile SPI might impact existing implementations based on this SPI. For more details, see the Upgrading Guide.
Changes to Freemarker templates to render pages based on the user profile and realm
In this release, the following templates were updated to make it possible to dynamically render attributes based on the user profile configuration set to a realm:
-
login-update-profile.ftl -
register.ftl -
update-email.ftl
For more details, see the Upgrading Guide.
New Freemarker template for the update profile page at first login through a broker
In this release, the server renders the update profile page when the user is authenticating through a broker for the
first time using the idp-review-user-profile.ftl template.
For more details, see the Upgrading Guide.
Java adapter deprecation and removal
Back in 2022 we announced the deprecation of Keycloak adapters in Keycloak 19. To give the community more time to adopt this was delayed.
With that in mind, this will be the last major release of Keycloak to include OpenID Connect and SAML adapters. As Jetty 9.x has not been supported since 2022 the Jetty adapter has been removed already in this release.
The generic Authorization Client library will continue to be supported, and aims to be used in combination with any other OAuth 2.0 or OpenID Connect libraries.
The only adapter we will continue to deliver is the SAML adapter for latest releases of WildFly and EAP 8.x. Reasoning for continuing to support this is down to the fact that the majority of the SAML codebase in Keycloak was a contribution from WildFly. As part of this contribution we agreed to maintain SAML adapters for WildFly and EAP in the long run.
Jetty adapter removed
Jetty 9.4 has not been supported in the community for a long time, and reached end-of-life in 2022. At the same time the adapter has not been updated or tested with more recent versions of Jetty. For these reasons the Jetty adapter has been removed from this release.
New Welcome Page
The 'welcome' page that appears at the first use of Keycloak is redesigned. It provides a better setup experience and conforms to the latest version of PatternFly. The simplified page layout includes only a form to register the first administrative user. After completing the registration, the user is sent directly to the Admin Console.
If you use a custom theme, you may need to update it to support the new welcome page. For details, see the Upgrading Guide.
New Account Console now the default
We introduced version 3 of the Account Console in Keycloak 22 as a preview feature. In this release, we are making it the default version, and deprecating version 2 in the process, which will be removed in a subsequent release.
This new version has built-in support for the user profile feature, which allows administrators to configure which attributes are available to users in the Account Console, and lands a user directly on their personal account page after logging in.
If you are using or extending the customization features of this theme, you may need to perform additional migrations. For more details, see the Upgrading Guide.
Keycloak JS
Using exports field in package.json
The Keycloak JS adapter now uses the exports field in its package.json. This change improves support for more modern bundlers like Webpack 5 and Vite, but comes with some unavoidable breaking changes. See the Upgrading Guide for more details.
PKCE enabled by default
The Keycloak JS adapter now sets the pkceMethod o...
23.0.7
Upgrading
Before upgrading refer to the migration guide for a complete list of changes.
All resolved issues
Enhancements
- #26810 Shorter lifespan for offline session cache entries in memory
storage
Bugs
- #22431 Localization: Admin UI doesn't pick up message bundles from realms other than master
admin/ui - #23786 Failure: FipsDistTest
ci - #25294 Kerberos principal attribute not found on LDAP user - even if kerberos authentication is off
ldap - #25731 /admin/realms/{realm}/groups Endpoint is slow
admin/api - #25883 ldap-group-mapper fails when empty member: attribute is present
ldap - #25912 LDAP federation reports "Creating new LDAP Store..." on every login
ldap - #25961 Native SQL Schema names broken on MySQL
storage - #26374 Workflow failure: Quarkus IT - FipsDistTest#testUnsupportedHttpsPkcs12KeyStoreInStrictMode
ci - #26529 Workflow failure: Quarkus IT - FipsDistTest#testUnsupportedHttpsPkcs12KeyStoreInStrictMode
ci - #26826 Freemarker erroneously escapes/sanitizes URL in template.ftl (&)
login/ui - #27120 Microsoft social login failure
testsuite
23.0.6
Upgrading
Before upgrading refer to the migration guide for a complete list of changes.