Upgrading Guide

Previous releases ignored any change to conf/cache-ispn.xml if the --cache-config-file option was not provided.

Starting from this release, when --cache-config-file is not set, the default Infinispan XML configuration file is conf/cache-ispn.xml as this is both the expected behavior and the implied behavior given the docs of the current and previous releases.

The embedded work cache needs to be configured as a replicated-cache for cache invalidation to work as expected.

Starting from this release, Keycloak check this at startup and will fail to start if it is not configured as such.

The following APIs for the JavaScript Authorization client are deprecated and will be removed in the next major release:

These APIs are no longer needed as initialization is done automatically on demand when calling methods on the KeycloakAuthorization instance. You can safely remove any code that depends on these APIs.

Starting from this release, Keycloak automatically enables the virtual thread pool support in both the embedded Infinispan and JGroups when running on OpenJDK 21. This removes the need to configure the JGroups thread pool, the need to align the JGroups thread pool with the HTTP worker thread pool, and reduces the overall memory footprint. To disable the virtual threads, add one of the Java system properties combinations to your deployment:

Previous versions of Keycloak used as a default UDP multicast to discover other nodes to form a cluster and to synchronize the replicated caches of Keycloak. This required multicast to be available and to be configured correctly, which is usually not the case in cloud environments.

Starting with this version, the default changes to the jdbc-ping configuration which uses Keycloak’s database to discover other nodes. As this removes the need for multicast network capabilities and UDP and no longer using dynamic ports for the TCP-based failure detection, this is a simplification and a drop-in replacement for environments which used the previous default. To enable the previous behavior, choose the transport stack udp which is now deprecated.

The Keycloak Operator will continue to configure kubernetes as a transport stack.

See the Configuring distributed caches guide for more information.

The udp, jdbc-ping-udp, tcp, azure, ec2 and google transport stacks have been deprecated. Users should use the TCP based jdbc-ping stack as a direct replacement.

When developing extensions for Keycloak, developers can now specify dependencies between provider factories classes by implementing the method dependsOn() in the ProviderFactory interface. See the Javadoc for a detailed description.

The format of KEYCLOAK_SESSION cookie was slightly updated to not contain any private data in plain text. Until now, the format of the cookie was realmName/userId/userSessionId. Now the cookie contains user session ID, which is hashed by SHA-256 and URL encoded. This can affect you just in case when implementing your own providers and relying on the format of internal Keycloak cookies.

The robots.txt file, previously included by default, is now removed. The default robots.txt file blocked all crawling, which prevented the noindex/nofollow directives from being followed. The desired default behaviour is for Keycloak pages to not show up in search engine results and this is accomplished by the existing X-Robots-Tag header, which is set to none by default. The value of this header can be overidden per-realm if a different behaviour is needed.

Any offline session in Keycloak is created from another online session. When the offline_access scope is requested, the current online session is used to create the associated offline session for the client. Therefore any offline_access request finished, until now, with two sessions, one online and one offline.

Starting with this version, Keycloak removes the initial online session if the offline_scope is directly requested as the first interaction for the session. The client retrieves the offline token after the code to token exchange that is associated to the offline session, but the previous online session is removed. If the online session has been used before the offline_scope request, by the same or another client, the online session remains active as today. Although the new behavior makes sense because the client application is just asking for an offline token, it can affect some scenarios that rely on having the online session still active after the initial offline_scope token request.

Keycloak introduces a new client scope at the realm level called service_account which is in charge of adding the specific claims for client_credentials grant (client_id, clientHost and clientAddress) via protocol mappers. This scope will be automatically assigned to and unassigned from the client when the serviceAccountsEnabled option is set or unset in the client configuration.

Previously, the three mappers (Client Id, Client Host and Client IP Address) where added directly to the dedicated scope when the client was configured to enable service accounts, and they were never removed.

In this release, admin events might hold additional details about the context when the event is fired. When upgrading you should expect the database schema being updated to add a new column DETAILS_JSON to the ADMIN_EVENT_ENTITY table.

Marshalling is the process of converting Java objects into bytes to send them across the network between Keycloak servers. With Keycloak 26, the marshalling library has changed from JBoss Marshalling to Infinispan Protostream. The libraries are not compatible between each other and, it requires some steps to ensure the session data is not lost.

To prevent losing user sessions upgrade to Keycloak 25 first and enable the persistent sessions feature as outlined in the migration guide for Keycloak 25.

The Operator will no longer default to the hostname v1 setting of proxy=passthrough. This allows deployments using hostname v2 for a fixed edge hostname to work as desired without additional options.

The following method was added to org.keycloak.cluster.ClusterProvider:

When multiple events are sent to the same taskKey, this method batches events and just perform a single network call. This is an optimization to reduce traffic and network related resources.

In Keycloak 26, the new method has a default implementation to keep backward compatibility with custom implementation. The default implementation performs a single network call per an event, and it will be removed in a future version of Keycloak.

With the goal of improving the scalability of groups, they are now removed directly from the database when removing a realm. As a consequence, group-related events like the GroupRemovedEvent are no longer fired when removing a realm.

If you have extensions handling any group-related event when a realm is removed, make sure to use the RealmRemovedEvent instead to perform any cleanup or custom processing when a realm, and their groups, are removed.

The GroupProvider interface is also updated with a new preRemove(RealmModel) method to force implementations to properly handle the removal of groups when a realm is removed.

User is automatically redirected to the path where Keycloak is hosted when the http-relative-path property is specified. It means when the relative path is set to /auth, and the user access localhost:8080/, the page is redirected to localhost:8080/auth.

The same applies to the management interface when the http-management-relative-path or http-relative-path property is specified.

It improves user experience as users no longer need to set the relative path to the URL explicitly.

Keycloak Pods will now have default affinities to prevent multiple instances from the same CR from being deployed on the same node, and all Pods from the same CR will prefer to be in the same zone to prevent stretch cache clusters.

In order to follow the best practices, the default CPU and memory limits/requests for the Operator were introduced. It affects both non-OLM and OLM installs. To override the default values for the OLM install, edit the resources section in the operator’s subscription.

The following items have been deprecated for removal in upcoming Keycloak versions with no replacement:

org.keycloak.common.util.Encode now always uses the UTF-8 charset for URL encoding instead relying implicitly on the file.encoding system property.

In this release, the LDAP connection pool configuration relies solely on system properties. The main reason is that the LDAP connection pool configuration is a JVM-level configuration rather than specific to an individual realm or LDAP provider instance.

Compared to previous releases, any realm configuration related to the LDAP connection pool will be ignored. If you are migrating from previous versions where any of the following settings are set to your LDAP provider(s), consider using system properties instead:

For more details, see Configuring the connection pool.

This release introduced the capability to easily add a custom footer to the login pages for the base/login and keycloak.v2/login theme. In order to use a custom footer, create a footer.ftl file in your custom login theme with the desired content.

For more details, see Adding a custom footer to a login theme.

In this release, revoked access tokens are written to the database and reloaded when the cluster is restarted by default when using the embedded caches.

To disable this behavior, use the SPI option spi-single-use-object-infinispan-persist-revoked-tokens as outlined in the All provider configuration guide.

The SPI behavior of SingleUseObjectProvider has changed that for revoked tokens only the methods put and contains must be used. This is enforced by default, and can be disabled using the SPI option spi-single-use-object-infinispan-persist-revoked-tokens.

Keycloak 26 introduces significant improvements to the recommended HA multi-site architecture, most notably:

As a consequence of the above changes, the following changes are required to your existing Keycloak deployments.

If you are using an external Infinispan in a single-site setup, this was not supported in earlier versions of Keycloak and it is not supported in Keycloak 26. To protect users from using it accidentally via a manual configuration in Keycloak’s cache XML or via the CLI options, this is now guarded with a feature flag cache-embedded-remote-store. It is marked as experimental and is therefore not supported. Keycloak 26 will not start with such a configuration and show an error instead unless this experimental feature is enabled.

If you have been using an external Infinispan to keep users logged in between restarts and upgrades, use the persistent-user-sessions feature instead which is enabled by default. The external Infinispan is then no longer necessary.

The experimental feature cache-embedded-remote-store will be removed in a future minor release.

It used to be difficult to regain access to a Keycloak instance when all admin users were locked out. The process required multiple advanced steps, including direct database access and manual changes. In an effort to improve the user experience, Keycloak now provides multiple ways to bootstrap a new admin account, which can be used to recover from such situations.

Consequently, the environment variables KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD have been deprecated. You should use KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD instead. These are also general options, so they may be specified via the cli or other config sources, for example --bootstrap-admin-username=admin. For more information, see the new Bootstrap admin and recovery guide.

The required action provider name is now returned via the kc_action parameter when redirecting back from an application initiated required action execution. This eases the detection of which required action was executed for a client. The outcome of the execution can be determined via the kc_action_status parameter.

Note: This feature required changes to the Keycloak JS adapter, therefore it is recommended to upgrade to the latest version of the adapter if you want to make use of this feature.

The class UserSessionCrossDCManager is deprecated and planned to be removed in a future version of Keycloak. Read the UserSessionCrossDCManager Javadoc for the alternative methods to use.

As part of the improvements around the scalability of realms and organizations when they have many identity providers, the realm representation no longer holds the list of identity providers. However, they are still available from the realm representation when exporting a realm.

To obtain the query the identity providers in a realm, prefer using the /realms/{realm}/identity-provider/instances endpoint. This endpoint supports filters and pagination.

The CLI command kc.[sh|bat] import now has placeholder replacement enabled. Previously placeholder replacement was only enabled for realm import at startup.

If you wish to disable placeholder replacement for the import command, add the system property -Dkeycloak.migration.replace-placeholders=false

The RealmProvider Java API now contains a new method Stream<RealmModel> getRealmsStream(String search) which allows searching for a realm by name. While there is a default implementation which filters the stream after loading it from the provider, implementations are encouraged to provide this with more efficient implementation.

Keycloak now determines the format of the keystore and trust store based on the file extension. If the file extension is .p12, .pkcs12 or .pfx, the format is PKCS12. If the file extension is .jks, .keystore or .truststore, the format is JKS. If the file extension is .pem, .crt or .key, the format is PEM.

You can still override automatic detection by specifying the https-key-store-type and https-trust-store-type explicitly. The same applies to the management interface and its https-management-key-store-type. Restrictions for the FIPS strict mode stay unchanged.

New indexes were added to the IDENTITY_PROVIDER table to improve the performance of queries that fetch the IDPs associated with an organization, and fetch IDPs that are available for login (those that are enabled, not link_only, not marked as hide_on_login).

If the table currently contains more than 300.000 entries, Keycloak will skip the creation of the indexes by default during the automatic schema migration, and will instead log the SQL statements on the console during migration. In this case, the statements must be run manually in the DB after Keycloak’s startup.

Also, the kc.org and hideOnLoginPage configuration attributes were migrated to the identity provider itself, to allow for more efficient queries when searching for providers. As such, API clients should use the getOrganizationId/setOrganizationId and isHideOnLogin/setHideOnLogin methods in the IdentityProviderRepresentation, and avoid setting these properties using the legacy config attributes that are now deprecated.

GELF support has been deprecated for a while now, and with this release it has been finally removed from Keycloak. Other log handlers are available and fully supported to be used as a replacement of GELF, for example Syslog. For details see the Logging guide.

Some of the paths for the common resources of the keycloak theme have changed, specifically the resources for third-party libraries. Make sure to update your custom themes accordingly:

Additionally, the following resources have been removed from the common theme:

If you previously used any of the removed resources in your theme, make sure to add them to your own theme resources instead.

Keycloak by default does not use XA datasources. However, this is considered unsafe if more than one datasource is used. Starting with this release, you need to use XA datasources if you are adding additional datasources to Keycloak. If the default datasource supports XA, you can do this by setting the --transaction-xa-enabled=true option. For additional datasources, you need to use the quarkus.datasource.<your-datasource-name>.jdbc.transactions=xa option in your quarkus.properties file. At most one datasource can be non-XA. Recovery isn’t supported when you don’t have persistent storage for the transaction store.

The deprecated hostname v1 feature was removed. This feature was deprecated in Keycloak 25 and replaced by hostname v2. If you are still using this feature, you must migrate to hostname v2. For more details, see the Configuring the hostname (v2) and the initial migration guide.

The deprecated proxy option was removed. This option was deprecated in Keycloak 24 and replaced by the proxy-headers option in combination with hostname options as needed. For more details, see using a reverse proxy and the initial upgrading guide.

Since the database is now the source of truth for user sessions, it is possible to restrict the size of the session caches to reduce memory usage. If you use the default conf/cache-ispn.xml file the caches for storing user and client sessions are by default configured to store only 10000 sessions and one owner for each entry.

Update your custom embedded Infinispan cache configuration file with configuration similar to one shown below for caches sessions, clientSessions, offlineSessions, and offlineClientSessions:

For more details proceed to the Configuring distributed caches guide.

Previous versions of Keycloak added a grace period of two minutes to idle times of user and client sessions. This was added due to a previous architecture where session refresh times were replicated asynchronously in a cluster. With persistent user sessions, this is no longer necessary, and therefore the grace period is now removed.

To keep the old behavior, update your realm configuration and extend the session and client idle times by two minutes.

Previous versions of Keycloak had supported automatic logout of the user and redirecting to the application by opening logout endpoint URL such as http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri. This functionality was deprecated in Keycloak 18 and has been removed in this version in favor of following the OpenID Connect specification.

As part of this change the following related configuration options for the SPI have been removed:

If you were still making use these options or the redirect_uri parameter for logout you should implement the OpenID Connect RP-Initiated Logout specification instead.

The --optimized startup option now requires the optimized server image to be built first. This can be achieved either by running kc.sh|bat build first or by any other server commands (like start, export, import) without the --optimized flag.

The org.keycloak.bom:keycloak-adapter-bom and org.keycloak.bom:keycloak-misc-bom BOM files are removed. The adapter BOM was no longer useful because most of the Java adapters are removed. The misc BOM had contained only one artifact, keycloak-test-helper, and that artifact is also removed in this release.

The maven artifact org.keycloak:keycloak-test-helper is removed in this release. The artifact provided a few helper methods for dealing with a Java admin client. If you use the helper methods, it is possible to fork them into your application if needed.

The JEE admin-client is removed in this release. We still keep supporting Jakarta admin-client.

There are now generalized events for updating (UPDATE_CREDENTIAL) and removing (REMOVE_CREDENTIAL) a credential. The credential type is described in the credential_type attribute of the events. The new event types are supported by the Email Event Listener.

The following event types are now deprecated and will be removed in a future version: UPDATE_PASSWORD, UPDATE_PASSWORD_ERROR, UPDATE_TOTP, UPDATE_TOTP_ERROR, REMOVE_TOTP, REMOVE_TOTP_ERROR

When running a start or start-dev command with the --import-realm option before the master realm exists, it will be imported if it exists in the import material. The previous behavior was that the master realm was created first, then its import skipped.

Our FIPS 140-2 integration is now tested and supported with version 2 of BouncyCastle FIPS libraries. This version is certified with Java 21. If you use FIPS 140-2 integration, it is recommended to upgrade BouncyCastle FIPS library to the versions mentioned in the latest documentation.

The BouncyCastle FIPS version 2 is certified with FIPS 140-3. So Keycloak can be FIPS 140-3 compliant as long as it is used on the FIPS 140-3 compliant system. This might be the RHEL 9 based system, which itself is compliant with the FIPS 140-3. But note that RHEL 8 based system is only certified for the FIPS 140-2.

The groups.setOrCreateChild() method has been removed from that JavaScript-based Admin Client. If you are still using this method then use the createChildGroup() or updateChildGroup() methods instead.

This release includes several changes to Keycloak JS library that should be taken into account. The main motivation for these changes is to de-couple the library from the Keycloak server, so that it can be refactored independently, simplifing the code and making it easier to maintain in the future. The changes are as follows:

When the provided build-time options differ at startup from the values persisted in the server image during the last optimized Keycloak build, Keycloak will now fail to start. Previously, a warning message was displayed in such cases.

With feature versions the features account3, admin2, and login2 have been renamed. When disabling a feature there is no need to use the version, for example the admin console is now disabled with --features-disabled=admin.

To use a specific version of login use --features=login:v1.

If an attacker launched many login attempts in parallel then the attacker could have more guesses at a password than the brute force protection configuration permits. This was due to the brute force check occurring before the brute force protector has locked the user. To prevent this race the Brute Force Protector now rejects all login attempts that occur while another login is in progress in the same server.

If, for whatever reason, the new feature wants to be disabled there is a startup factory option:

When a client scope or the full realm are deleted the associated user consents should also be removed. A new index over the table USER_CONSENT_CLIENT_SCOPE has been added to increase the performance.

Note that, if the table contains more than 300.000 entries, by default Keycloak skips the creation of the indexes during the automatic schema migration and logs the SQL statements to the console instead. The statements must be run manually in the DB after Keycloak’s startup. Check the Upgrading Guide for details on how to configure a different limit.

Hostname v2 options are supported by default, as the old hostname options are deprecated and will be removed in the following releases. New options are activated by default, so Keycloak will not recognize the old options.

List of necessary migrations:

As you can see, the *-url suffixes were removed for hostname and hostname-admin options. Option hostname accepts both hostname and URL, but hostname-admin accepts only full URL now.

Additionally, there is no way to set path or port separately. You can achieve it by providing the full URL for the hostname and hostname-admin options.

If the port is not part of the URL, it is dynamically resolved from the incoming request headers.

HTTPS is no longer enforced unless it is part of hostname and hostname-admin URLs. If not specified, the used protocol (http/https) is dynamically resolved from the incoming request. The hostname-strict-https option is removed.

Previous versions of Keycloak stored only offline user and offline client sessions in the databases. The new feature persistent-user-sessions 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.

Metrics for the embedded caches are now enabled by default. To enable histograms for latencies, set the option cache-metrics-histograms-enabled to true.

The metrics provided by Keycloak now include HTTP server metrics starting with http_server. See below for some examples.

Use the new options http-metrics-histograms-enabled and http-metrics-slos to enable default histogram buckets or specific buckets for service level objectives (SLOs). Read more about histograms in the Prometheus documentation about histograms on how to use the additional metrics series provided in http_server_requests_seconds_bucket.

In Keycloak 24 release, we had a change in the password hashing algorithm which resulted in an increased CPU usage. To address that, we opted to a different default hashing algorithm Argon2 for non-FIPS environments which brings the CPU usage back to where it was prior to the Keycloak 24 release.

In some scenarios like brokering Keycloak uses HTTP to talk to external servers. To avoid a denial of service when those providers send too much data, Keycloak now restricts responses to 10 MB by default.

Users can configure this limit by setting the provider configuration option spi-connections-http-client-default-max-consumed-response-size:

The default for spi-truststore-file-hostname-verification-policy and the new tls-hostname-verifier option is now DEFAULT, rather than WILDCARD. The WILDCARD and STRICT option values have been deprecated - you should simply rely upon DEFAULT instead.

Behavior supported by WILDCARD, that is not supported by DEFAULT: * allows wildcards in subdomain names (e.g. *.foo.com) to match anything, including multiple levels (e.g. a.b.foo.com). * allows matching against well known public suffixes - e.g. foo.co.gl may match *.co.gl

Behavior supported by STRICT, that is not supported by DEFAULT: * STRICT uses a small exclusion list for 2 or 3 letter domain names ending in a 2 letter top level (*.XXX.YY) when determining if a wildcard matches. Instead DEFAULT uses a more complete list of public suffix rules and exclusions from https://publicsuffix.org/list/

It is not expected that you should be relying upon these behaviors from the WILDCARD or STRICT options.

Keycloak now does not display the message You are already logged in to the end user when an authentication session expires and user is already logged-in. Instead it redirects the error about the expired authentication session to the client application, so the client can act on it and restart authentication as described in the Server Administration Guide authentication sessions chapter. You may consider updating your applications to being able to handle this error.

The module org.keycloak:keycloak-model-legacy module was deprecated in a previous release and is removed in this release. Use the org.keycloak:keycloak-model-storage module instead.

The old behavior to preload offline sessions at startup is now removed after it has been deprecated in the previous release.

Options cache, cache-stack, and cache-config-file are no longer build options, and they can be specified only during runtime. This eliminates the need to execute the build phase and rebuild your image due to them. Be aware that they will not be recognized during the build phase, so you need to remove them from the build phase and add them to the runtime phase. If you do not add your current caching options to the runtime phase, Keycloak will fall back to the default caching settings.

How kcadm and kcreg parse and handle options and parameters has changed. Error messages from usage errors, the wrong option or parameter, may be slightly different than previous versions. Also usage errors will have an exit code of 2 instead of 1.

When searching for users by user attribute, Keycloak no longer searches for user attribute names forcing lower case comparisons. This means Keycloak’s native index on the user attribute table will now be used when searching. If you have created your own index based on `lower(name)`to speed up searches, you can now remove it.

The new client scope named basic is added as a realm "default" client scope and hence will be added to all newly created OIDC clients. The client scope is also automatically added to all existing OIDC clients during migration.

This scope contains preconfigured protocol mappers for the following claims:

This provides additional help to reduce the number of claims in a lightweight access token, but also gives the chance to configure claims that were always added automatically.

The session_state claim, which contains the same value as the sid claim, is now removed from all tokens as it is not required according to the OpenID Connect Front-Channel Logout and OpenID Connect Back-Channel Logout specifications. The session_state claim remains present in the Access Token Response in accordance with OpenID Connect Session Management specification.

Note that the setSessionState() method is also removed from the IDToken class in favor of the setSessionId() method, and the getSessionState() method is now deprecated.

A new Session State (session_state) mapper is also included and can be assigned to client scopes (for instance basic client scope) to revert to the old behavior.

If an old version of the JS adapter is used, the Session State (session_state) mapper should also be used by using client scopes as described above.

The sub claim, which was always added to the access token, is now added by default but using a new Subject (sub) protocol mapper.

The Subject (sub) mapper is configured by default in the basic client scope. Therefore, no extra configuration is required after upgrading to this version.

If you are using the Pairwise subject identifier mapper to map a sub claim for an access token, you can consider disabling or removing the Subject (sub) mapper, however it is not strictly needed as the Subject (sub) protocol mapper is executed before the Pairwise subject identifier mapper and hence the pairwise value will override the value added by Subject (sub) mapper. This may apply also to other custom protocol mapper implementations, which override the sub claim, as the Subject (sub) mapper is currently executed as first protocol mapper.

You can use the Subject (sub) mapper to configure the sub claim only for access token, lightweight access token, and introspection response. IDToken and Userinfo always contain sub claim.

The mapper has no effects for service accounts, because no user session exists, and the sub claim is always added to the access token.

The nonce claim is now only added to the ID token strictly following the OpenID Connect Core 1.0 specification. As indicated in the specification, the claim is compulsory inside the ID token when the same parameter was sent in the authorization request. The specification also recommends to not add the nonce after a refresh request. Previously, the claim was set to all the tokens (Access, Refresh and ID) in all the responses (refresh included).

A new Nonce backwards compatible mapper is also included in the software that can be assigned to client scopes to revert to the old behavior. For example, the JS adapter checked the returned nonce claim in all the tokens before fixing issue #26651 in version 24.0.0. Therefore, if an old version of the JS adapter is used, the mapper should be added to the required clients by using client scopes.

The userId in the REFRESH_TOKEN event is now always taken from user session instead of sub claim in the refresh token. The userId in the REFRESH_TOKEN_ERROR event is now always null. The reason for this change is that the value of the sub claim in the refresh token may be null with the introduction of the optional sub claim or even different from the real user id when using pairwise subject identifiers or other ways to override the sub claim.

However a refresh_token_sub detail is now added as backwards compatibility to have info about the user in the case of missing userId in the REFRESH_TOKEN_ERROR event.

If you use the latest Keycloak server with older versions of the javascript adapter in your applications, you may be affected by the token changes mentioned above as previous versions of javascript adapter rely on the claims, which were added by Keycloak, but not supported by the OIDC specification. This includes:

You can add the protocol mappers directly to the corresponding client or to some client scope, which can be used by your client applications relying on older versions of the Keycloak Javascript adapter. Some more details are in the previous sections dedicated to session_state and nonce claims.

http-pool-max-threads if left unset will default to the greater of 50 or 4 x (available processors). Previously it defaulted to the greater of 200 or 8 x (available processors). Reducing the number or task threads for most usage scenarios will result in slightly higher performance due to less context switching among active threads.

The /health and /metrics endpoints are accessible on the management port 9000, which is turned on by default. That means these endpoints are no longer exposed to the standard Keycloak ports 8080 and 8443.

In order to reflect the old behavior, use the property --legacy-observability-interface=true, which will not expose these endpoints on the management port. However, this property is deprecated and will be removed in future releases, so it is recommended not to use it.

The management interface uses a different HTTP server than the default Keycloak HTTP server, and it is possible to configure them separately. Beware, if no values are supplied for the management interface properties, they are inherited from the default Keycloak HTTP server.

For more details, see Configuring the Management Interface.

Keycloak has never escaped slashes in the group paths. Because of that, a group named group/slash child of top uses the full path /top/group/slash, which is clearly misleading. Starting with this version, the server can be started to perform escaping of those slashes in the name:

The escape char is the tilde character ~. The previous example results in the path /top/group~/slash. The escape marks the last slash is part of the name and not a hierarchy separator.

The escaping is currently disabled by default because it represents a change in behavior. Nevertheless enabling escaping is recommended and it can be the default in future versions.

The method EnvironmentDependentProviderFactory.isSupported() was deprecated for several releases and has now been removed.

Instead, implement isSupported(Config.Scope config).

In version 22.0.2 the OAuh 2.0 social provider for LinkedIn was replaced by a new OpenId Connect implementation. The legacy provider was deprecated but not removed, just in case it was still functional in some existing realms. Keycloak 25.0.0 is definitely removing the old provider and its associated linkedin-oauth feature. From now on, the default LinkedIn social provider is the only option available.

These queries performed poorly when the RESOURCE_SERVER_RESOURCE and RESOURCE_SERVER_PERM_TICKET tables had over 100k entries and users were granted access to over 1k resources. The queries were simplified and new indexes for the requester and owner columns were introduced.

The new indexes are both applied to the RESOURCE_SERVER_PERM_TICKET table. If the table currently contains more than 300.000 entries, Keycloak will skip the creation of the indexes by default during the automatic schema migration, and will instead log the SQL statements on the console during migration. In this case, the statements must be run manually in the DB after Keycloak’s startup.

See the Upgrading Guide for details on how to configure a different limit.

The following methods were removed from the AccessToken class:

The following methods were removed from the IDToken class:

The following methods were removed from the JsonWebToken class:

You should also expect both exp and nbf claims not set in tokens as they are optional. Previously, these claims were being set with a value of 0 what does not make mush sense because their value should be a valid NumericDate.

As a consequence of the removal of deprecated methods from AccessToken, IDToken, and JsonWebToken, the SingleUseObjectKeyModel also changed to keep consistency with the method names related to expiration values.

The previous getExpiration method is now deprecated and you should prefer using new newly introduced getExp method to avoid overflow after 2038.

Method String encode(String rawPassword, int iterations) on the interface org.keycloak.credential.hash.PasswordHashProvider is deprecated. The method will be removed in one of the future Keycloak releases. It might be Keycloak 27 release.

The method org.keycloak.common.util.CollectionUtil.intersection has been removed. You should use the 'java.util.Collection.retainAll' instead on an existing collection.

org.keycloak.common.util.Resteasy has been deprecated. You should use the org.keycloak.util.KeycloakSessionUtil to obtain the KeycloakSession instead.

It is highly recommended to avoid obtaining the KeycloakSession by means other than when creating your custom provider.

In previous versions the session max lifespan and idle timeout calculation was slightly different when validating if a session was still valid. Since now that validation uses the same code than the rest of the project.

If the session is using the remember me feature, the idle timeout and max lifespan are the maximum value between the common SSO and the remember me configuration values.

Keycloak now requires a Infinispan server version of at least 15.0.0 for external Infinispan deployments. An external Infinispan deployment is supported for multi-site setups as outlined in the HA guide.

The Oracle Database JDBC driver is no longer part of the Keycloak distribution. If you wish to use Oracle DB, you must manually install a version of the Oracle Driver that is compatible with your specific environment. Instructions for this process can be found in the Configuring the database guide.

The following variables were deprecated in the Admin theme and will be removed in a future version:

The following variables were deprecated in the Account theme and will be removed in a future version:

The methods String getCurrentRefreshToken(), void setCurrentRefreshToken(String currentRefreshToken), int getCurrentRefreshTokenUseCount(), and void setCurrentRefreshTokenUseCount(int currentRefreshTokenUseCount) in the interface org.keycloak.models.AuthenticatedClientSessionModel are deprecated. They have been replaced by similar methods that require an identifier as a parameter such as getRefreshToken(String reuseId) to manage multiple refresh tokens within a client session. The methods will be removed in one of the future Keycloak releases. It might be Keycloak 27 release.

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.

If you are updating user attributes through the Admin User API without passing all the attributes that the administrator has write permissions, the missing attributes will be removed. On the other hand, if an attribute is marked as read-only for administrators, not sending the attribute won’t remove it.

See the User Profile Documentation for the details about the user profile settings.

To properly support multiple user storage providers within a realm, the org.keycloak.userprofile.UserProfileDecorator interface has changed.

The decorateUserProfile method is no longer invoked when parsing the user profile configuration for the first time (and caching it), but every time a user is being managed through the user profile provider. As a result, the method changed its contract to:

Differently than the previous contract and behavior, this method is only invoked for the user storage provider from where the user was loaded from.

Because of security concerns, the redirect URI verification now performs a exact string matching (no wildcard involved) if the passed redirect uri contains a userinfo part or its path accesses parent directory (/../).

The full wildcard * can still be used as a valid redirect in development for http(s) URIs with those characteristics. In production environments a exact valid redirect URI without wildcard needs to be configured for any URI of that type.

Please note that wildcard valid redirect URIs are not recommended for production and not covered by the OAuth 2.0 specification.

The Account REST endpoint for removing the credential of the user is deprecated. Starting at this version, the Account Console no longer uses this endpoint. It is replaced by the Delete Credential application-initiated action, which is triggered by the Account Console when a user want to remove the credential of a user.

The release notes for Keycloak 24.0.0 have been updated with corrected description of the expected performance impact for the change, as well as sizing guide.

The 'welcome' theme has has been updated to use a new layout and now uses PatternFly 5, rather than PatternFly 3. If you are extending the theme, or providing your own, you may need to update it as follows:

If you were previously extending the now deprecated version 2 of the Account Console theme, you will need to update your theme to use the new version 3 of the Account Console theme. The new version of the Account Console theme comes with some changes in regards to how it is customized. To start with a clean slate, you can follow the new customization quickstart.

To move your custom theme start by changing the parent to the new theme:

If you have any custom React components, you will import React directly, rather than using a relative path:

If you are using content.json to customize the theme there are some changes to the structure of the file, specifically:

If you are loading Keycloak JS directly from the Keycloak server, this section can be safely ignored. If you are loading Keycloak JS from the NPM package and are using a bundler like Webpack, Vite, and so on, you might need to make some changes to your code. The Keycloak JS package now uses the exports field in the package.json file. This means that you might have to change your imports:

It is no longer allowed to have the same feature in both the --features and --features-disabled list. The feature should appear in only one list.

The usage of unversioned feature names, such as docker, in the --features list will allow for the most supported / latest feature version to be enabled for you. If you need more predictable behavior across releases, reference the particular version you want instead, such as docker:v1.

The spi-truststore-file-* options and the truststore related options https-trust-store-* are deprecated. Therefore, use the new default location for truststore material, conf/truststores, or specify your desired paths by using the truststore-paths option. For details, see the relevant guide.

The tls-hostname-verifier property should be used instead of the spi-truststore-file-hostname-verification-policy property.

A collateral effect of the changes is that now the truststore provider is always configured with some certificates (at least the default java trusted certificates are present). This new behavior can affect other parts of Keycloak.

For example, webauthn registration can fail if attestation conveyance was configured to Direct validation. Previously, if the truststore provider was not configured the incoming certificate was not validated. But now this validation is always performed. The registration fails with invalid cert path error as the certificate chain sent by the dongle is not trusted by Keycloak. The Certificate Authorities of the authenticator need to be present in the truststore provider to correctly perform the attestation.

The --proxy option has been deprecated and will be removed in a future release. The following table explains how the deprecated option maps to supported options.

You can also set the proxy headers when using the Operator:

Both org.keycloak.representations.idm.UserRepresentation and org.keycloak.representations.account.UserRepresentation representation classes have changed so that the root user attributes (such as username, email, firstName, lastName, and locale) have a consistent representation when fetching or sending the representation payload to the Admin and Account APIS, respectively.

The username, email, firstName, lastName, and locale attributes were moved to a new org.keycloak.representations.idm.AbstractUserRepresentation base class.

Also the getAttributes method is targeted for representing only custom attributes, so you should not expect any root attribute in the map returned by this method. This method is mainly targeted for clients when updating or fetching any custom attribute for a give user.

In order to resolve all the attributes including the root attributes, a new getRawAttributes method was added so that the resulting map also includes the root attributes. However, this method is not available from the representation payload and it is targeted to be used by the server when managing user profiles.

Option https-client-auth had been treated as a run time option, however this is not supported by Quarkus. The option needs to be handled at build time instead.

Starting with this release, the first member of a Keycloak cluster will load remote sessions sequentially instead of in parallel. If offline session preloading is enabled, those will be loaded sequentially as well.

The previous code led to high resource-consumption across the cluster at startup and was challenging to analyze in production environments and could lead to complex failure scenarios if a node was restarted during loading. Therefore, it was changed to sequential session loading.

For offline sessions, the default in this and previous versions of Keycloak is to load those sessions on demand, which scales better with a lot of offline sessions than the attempt to preload them in parallel. Setups that use this default setup are not affected by the change of the loading strategy for offline sessions. Setups that have offline session preloading enabled should migrate to a setup where offline-session preloading is disabled.

The default behavior of Keycloak is to load offline sessions on demand. The old behavior to preload them at startup is now deprecated, as preloading them at startup does not scale well with a growing number of sessions, and increases Keycloak memory usage. The old behavior will be removed in a future release.

To re-enable old behavior while it is deprecated and not removed yet, use the feature flag and the SPI option as shown below:

The API of UserSessionProvider deprecated the method getOfflineUserSessionByBrokerSessionId(RealmModel realm, String brokerSessionId). Instead of this method, use getOfflineUserSessionByBrokerUserIdStream(RealmModel, String brokerUserId) to first get the sessions of a user, and then filter by the broker session ID as needed.

When enabling metrics for Keycloak’s embedded caches, the metrics now use labels for the cache manager and the cache names.

To revert the change for an installation, use a custom Infinispan XML configuration and change the configuration as follows:

As of this release, Keycloak supports storing and searching by user attribute values longer than 255 characters, which was previously a limitation.

In setups where users are allowed to update attributes, for example, via the account console, prevent denial of service attacks by adding validations. Ensure that no unmanaged attributes are allowed and all editable attributes have a validation that limits the input length.

For unmanaged attributes, the maximum length is 2048 characters. For managed attributes, the default maximum length is 2048 characters. Administrator can change this by adding a validator of type length.

This change adds new indexes on the tables USER_ATTRIBUTE and FED_USER_ATTRIBUTE. If those tables contain more than 300000 entries, Keycloak will skip the index creation by default during the automatic schema migration and instead log the SQL statement on the console during migration to be applied manually after Keycloak’s startup. See the Upgrading Guide for details on how to configure a different limit.

In this release, the API will use the email-verification.ftl template instead of executeActions.ftl.

If you have customized the executeActions.ftl template to modify how users verify their email using this API, ensure that you transfer your modifications to the new template.

A new parameter called lifespan will be introduced to allow overriding of the default lifespan value (12 hours).

If you prefer the previous behavior, use the execute-actions-email API as follows.

The compatibility mode for SAML encryption introduced in version 21 is now removed. The system property keycloak.saml.deprecated.encryption is not managed anymore by the server. The clients which still used the old signing key for encryption should update it from the new IDP configuration metadata.

In this release, we adapted the password hashing defaults to match the OWASP recommendations for Password Storage.

As part of this change, the default password hashing provider has changed from pbkdf2-sha256 to pbkdf2-sha512. Also, the number of default hash iterations for pbkdf2 based password hashing algorithms changed as follows:

If a realm does not explicitly configure a password policy with hashAlgorithm and hashIterations, then the new configuration will take effect on the next password based login, or when a user password is created or updated.

Secrets and ConfigMaps referenced via the Keycloak CR will now be polled for changes, rather than watched via the api server. It may take around 1 minute for changes to be detected.

This was done so to not require label manipulation on those resources. After upgrading if any Secret still has the operator.keycloak.org/component label, it may be removed or ignored.

After removal of the Map Store the following configuration options were renamed:

After removal of the Map Store the following modules were renamed:

and org.keycloak:keycloak-model-legacy module was deprecated and will be removed in the next release in favour of org.keycloak:keycloak-model-storage module.

There is now a new event USER_DISABLED_BY_TEMPORARY_LOCKOUT when a user is temporarily locked out by the brute force protector. The log with ID KC-SERVICES0053 has been removed as the new event offers the information in a structured form.

As it is a success event, the new event is logged by default at the DEBUG level. Use the setting spi-events-listener-jboss-logging-success-level as described in the Event listener chapter in the Server Administration Guide to change the log level of all success events.

To trigger custom actions or custom log entries, write a custom event listener as described in the Event Listener SPI in the Server Developer Guide.

The property keys used by the operator for advanced configuration have changed from operator.keycloak to kc.operator.keycloak.

When no resources options are specified in the Keycloak CR and KeycloakRealmImport CR, default values are used. The default requests memory for Keycloak deployment and the realm import Job is set to 1700MiB, and the limits memory is set to 2GiB.

As part of refactoring cookie handling in Keycloak there are some changes to how cookies are set:

For custom extensions there may be some changes needed:

The algorithm that Keycloak uses to sign internal tokens (a JWT which is consumed by Keycloak itself, for example a refresh or action token) is being changed from HS256 to the more secure HS512. A new key provider named hmac-generated-hs512 is now added for realms. Note that in migrated realms the old hmac-generated provider and the old HS256 key are maintained and still validate tokens issued before the upgrade. The HS256 provider can be manually deleted when no more old tokens exist following the rotating keys guidelines.

The JVM options -Xms and -Xmx were replaced by -XX:InitialRAMPercentage and -XX:MaxRAMPercentage when running in a container. Instead of the static maximum heap size settings, Keycloak specifies the maximum as 70% of the total container memory.

As the heap size is dynamically calculated based on the total container memory, you should always set the memory limit for the container.

For more details, see the Running Keycloak in a container guide.

With sunsetting of the underlying library providing integration with GELF, Keycloak will no longer support the GELF log handler out-of-the-box. This feature will be removed in a future release. If you require an external log management, consider using file log parsing.

Because of issue #25078, the jboss-logging message values are now quoted (character " by default) and sanitized to prevent any line break. There are two new options in the provider (spi-events-listener-jboss-logging-sanitize and spi-events-listener-jboss-logging-quotes) that allow you to customize the new behavior. For example, to avoid both sanitization and quoting, the server can be started in this manner:

For more information about the options, see all provider configuration guide.

Version 23.0.0 introduced a new endpoint getSubGroups ("children") on the Groups resource, where the meaning of the parameter briefRepresentation meant the retrieval of full representations of the sub groups. The meaning is now changed to return the brief representation.

Version 1.8.0 introduced a lower-case for the hostname and scheme when comparing a redirect URI with the specified valid redirects for a client. Unfortunately it did not fully work in all the protocols, and, for example, the host was lower-cased for http but not for https. As OAuth 2.0 Security Best Current Practice advises to compare URIs using exact string matching, Keycloak will follow the recommendation and for now on valid redirects are compared with exact case even for the hostname and scheme.

For realms relying on the old behavior, the valid redirect URIs for their clients should now hold separate entries for each URI that should be recognized by the server.

Although it introduces more steps and verbosity when configuring clients, the new behavior enables more secure deployments as pattern-based checks are frequently the cause of security issues. These issues are due to how they are implemented and how they are configured.

Older versions of the operator created a Secret to track watched Secrets. Newer versions of the operator no longer use the -secrets-store Secret, so it may be deleted.

If you are on 23.0.0 or 23.0.1 and see "org.keycloak.operator.controllers.KeycloakAdminSecretDependentResource → java.lang.IllegalStateException: More than 1 secondary resource related to primary" in the operator log then either delete the -secrets-store Secret, or upgrade to 23.0.2 where this is no longer an issue.

RFC 9207 OAuth 2.0 Authorization Server Issuer Identification specification adds the parameter iss in the OAuth 2.0/OpenID Connect Authentication Response for realizing secure authorization responses.

In past releases, we did not have this parameter, but now Keycloak adds this parameter by default, as required by the specification.

However, some OpenID Connect / OAuth2 adapters, and especially older Keycloak adapters, may have issues with this new parameter.

For example, the parameter will be always present in the browser URL after successful authentication to the client application. In these cases, it may be useful to disable adding the iss parameter to the authentication response. This can be done for the particular client in the Keycloak Admin Console, in client details in the section with OpenID Connect Compatibility Modes, described in Compatibility with older adapters. Dedicated Exclude Issuer From Authentication Response switch exists, which can be turned on to prevent adding the iss parameter to the authentication response.

JPA allows wildcards % and _ when searching, while other providers like LDAP allow only *. As * is a natural wildcard character in LDAP, it works in all places, while with JPA it only worked at the beginning and the end of the search string. Starting with this release the only wildcard character is * which work consistently across all providers in all places in the search string. All special characters in a specific provider like % and _ for JPA are escaped. For exact search, with added quotes such as "w*ord", the behavior remains the same as in previous releases.

This release now follows the standard mechanisms of Java and later, which assumes resource bundle files to be encoded in UTF-8.

Previous versions of Keycloak supported specifying the encoding in the first line with a comment like # encoding: UTF-8, which is no longer supported and is ignored.

Message properties files for themes are now read in UTF-8 encoding, with an automatic fallback to ISO-8859-1 encoding. If you are using a different encoding, convert the files to UTF-8.

Before this release, both realm (User Realm Role) and client (User Client Role) protocol mappers were mapping a stringfied JSON array when the Multivalued setting was disabled.

However, the Multivalued setting indicates whether the claim should be mapped as a list or, if disabled, only a single value from the same list of values.

In this release, the role and client mappers now map to a single value from the effective roles of a user when they are marked as single-valued (Multivalued disabled).

In this version we want to introduce a toggle to hide/show password inputs.

In general all <input type="password" name="password" /> are encapsulated within a div now. The input element is followed by a button which toggles the visibility of the password input.

Old code example:

New code example:

When running on OpenShift, with ingress enabled, and with the spec.ingress.classname set to openshift-default, you may leave the spec.hostname.hostname unpopulated in the Keycloak CR. The operator will assign a default hostname to the stored version of the CR similar to what would be created by an OpenShift Route without an explicit host - that is ingress-namespace.appsDomain If the appsDomain changes, or should you need a different hostname for any reason, then update the Keycloak CR.

The auto-build CLI option has been marked as deprecated for a long time. In this release, it was completely removed, and it is no longer supported.

When executing the start command, the server is automatically built based on the configuration. In order to prevent this behavior, set the --optimized flag.

The kc.sh no longer uses an additional shell eval on parameters and the environment variables JAVA_OPTS_APPEND and JAVA_ADD_OPENS, thus the continued use of double escaping/quoting will result in the parameter being misunderstood. For example instead of

Use a single escape:

This change also means you cannot invoke kc.sh using a single quoted value of all arguments. For example you can no longer use

it must instead be individual arguments

Similarly instead of

it must instead be individual arguments

The usage of individual arguments is also required in Dockerfile run commands.

The form action RegistrationProfile (displayed in the UI of authentication flows as Profile Validation) was removed from the codebase and also from all authentication flows. By default, it was in the built-in registration flow of every realm. The validation of user attributes as well as creation of the user including all that user’s attributes is handled by RegistrationUserCreation form action and hence RegistrationProfile is not needed anymore. There is usually no further action needed in relation to this change, unless you used RegistrationProfile class in your own providers.

A new method has been added to allow for searching and paging through top level groups. If you implement this interface you will need to implement the following method:

Endpoint GET {keycloak server}/realms/{realm}/groups/{group_id}/children added as a way to get subgroups of specific groups that support pagination

Relying on RESTEasy Classic is not longer an option because it is not available anymore. Migration will be needed for SPI’s and code that is relying on RESTEasy Classic and related packages part of org.jboss.resteasy.spi.*.

The endpoint POST {keycloak server}/realms/{realm}/partial-export and the corresponding action in the admin console now require manage-realm permission for execution instead of view-realm. This endpoint exports the realm configuration into a JSON file and the new permission is more appropriate. The parameters exportGroupsAndRoles and exportClients, which include the realm groups/roles and clients in the export respectively, continue managing the same permissions (query-groups and view-clients).

Since this release, Keycloak supports long value for EventEntity details column. Therefore, it no longer supports options for trimming event detail length --spi-events-store-jpa-max-detail-length and --spi-events-store-jpa-max-field-length.

This release includes many fixes and updates that are related to user profile as we are working on promoting this feature from preview to officially supported. Minor changes exist for the SPI such as the newly added method boolean isEnabled(RealmModel realm) on UserProfileProvider interface. Also some user profile classes and some validator related classes (but not builtin validator implementations) were moved from keycloak-server-spi-private to keycloak-server-spi module. However, the packages for java classes remain the same. You might be affected in some corner cases, such as when you are overriding the built-in implementation with your own UserProfileProvider implementation. However, note that UserProfileProvider is an unsupported SPI.

The Map Store has been an experimental feature in previous releases. Starting with this release, it is removed and users should continue to use the current JPA store.

Since this release, it is no longer possible to use --storage related CLI options. The modules keycloak-model-map* have been removed.

All translations are moved into one file for the Admin Console. If you have made your own translations or extended the Admin Console you will need to migrate them to this new format. Also if you have "overrides" in your database, you will have to remove the namespace from the keys. Some keys are the same only in different namespaces, this is most obvious to help. In these cases we have postfix the key with Help.

If you want you can use this node script to help with the migration. It will take all the single files and put them into a new one and also take care of some of the mapping:

Save this into a file called transform.mjs in your public/locale/<language> folder and run it with:

A new parameter --spi-user-profile-declarative-user-profile-max-email-local-part-length is added to set max email local part length taking backwards compatibility into consideration. The default value is 64. Example of usage:

The option Never expires is now removed from all the combos of the Advanced Settings client tab. This option was misleading because the different lifespans or idle timeouts were never infinite, but limited by the general user session or realm values. Therefore, this option is removed in favor of the other two remaining options: Inherits from the realm settings (the client uses general realm timeouts) and Expires in (the value is overridden for the client). Internally the Never expires was represented by -1. Now that value is shown with a warning in the Admin Console and cannot be set directly by the administrator.

A new social identity provider called LinkedIn OpenID Connect has been introduced for the business and employment-focused platform. LinkedIn released recently a new product for developers called Sign In with LinkedIn using OpenID Connect. The product provides a new way to authenticate members using OpenID Connect, but the default OpenID Connect v1.0 identity provider does not work with it at present time. For that reason, Keycloak adds this new identity provider as the specific social provider for the new product.

The old LinkedIn way based on OAuth seems to be completely removed from the developer portal. How the existing LinkedIn social provider is working with current applications is not clear. Keycloak maintains the old provider renamed to LinkedIn (deprecated), but in a deprecated feature called linkedin-oauth which is disabled by default. It will be removed in future versions. Please enable it again at startup if needed:

Keycloak migrated its codebase from Java EE (Enterprise Edition) to its successor Jakarta EE, which brings various changes into Keycloak.

We have upgraded all Jakarta EE specifications in order to support Jakarta EE 10, such as:

Jakarta EE 10 provides a modernized, simplified, lightweight approach to building cloud-native Java applications. The main changes provided within this initiative are changing the namespace from javax.* to jakarta.*. It does not apply for javax.* packages provided directly in the JDK, such as javax.security, javax.net, javax.crypto, etc.

You can be affected by these changes in your custom extensions, providers or JPA entities.

Keycloak upgraded to version 3 of the Quarkus Java framework. Quarkus 3 continues the tradition of propelling Java development by moving fast and providing a cutting-edge user experience with the latest technologies. It continues to improve overall performance and efficiency.

Quarkus 3 is based on Jakarta EE 10, the same as Keycloak, creating smooth interoperability between them. In addition, it contains Eclipse MicroProfile 6, which aligns with Jakarta EE 10 Core Profile. The central part of the Quarkus 3 upgrade is built-in support for JPA 3.1 and Hibernate ORM 6.

Keycloak now benefits from the upgrade to Hibernate ORM 6.2, which includes improved performance, better SQL, modern JDK support, and support for modern RDBMS features. The performance improvements primarily affect JDBC, HQL Translation, and Criteria Translation.

If you have custom providers or JPA entities, these changes may affect you.

We recommend reviewing the Quarkus migration guide or the Hibernate release notes for more information.

The legacy Promise API methods have been removed from the Keycloak JS adapter. This means that calling .success() and .error() on promises returned from the adapter is no longer possible. Instead standardized Promise methods such as .then() and .catch() should be used.

In previous releases, the export and import commands required a build command to be run first. Starting with this release, the export and import commands perform an automatic rebuild of Keycloak if a build time configuration has changed.

When migrating existing scripts that run a build command first, migrate by adding the --optimized command line option to the export and import command to avoid Keycloak automatically re-building the image. Not adding the --optimized option in this might make Keycloak trigger a rebuild and revert to the default values, and then connecting to the database for export and import will not work.

The following examples assume that runtime parameters like a database password are provided via a configuration file or an environment variable.

In previous releases the export and import commands allowed runtime parameters such as a database URL only in configuration files or environment variables. Starting with this release, those runtime parameters are now available on the command line as well. Use the --help option to find out about the supported parameters.

After the upgrade to Jakarta EE, artifacts for Keycloak Admin clients were renamed to more descriptive names with consideration for long-term maintainability. We still provide two separate Keycloak Admin clients, one with Jakarta EE and the other with Java EE support.

We stopped releasing the org.keycloak:keycloak-admin-client-jakarta artifact. The default one for the Keycloak Admin client with Jakarta EE support is org.keycloak:keycloak-admin-client (since version 22.0.0).

The new artifact with Java EE support is org.keycloak:keycloak-admin-client-jee.

Keycloak’s proxy configuration setting for mode passthrough no longer parses HTTP forwarding headers in the request, as when a proxy forwards an HTTPS connection in passthrough mode, a proxy is unable to add, remove or update HTTP headers.

Installations that want the HTTP headers in the client’s request to be parsed should use the edge or reencrypt setting.

See Using a reverse proxy for details.

This change only may affect you when you are using realm localization messages.

Up to this version, the resolving of fallback messages was inconsistent across themes, when realm localization messages were used. More information can be found in the following issue.

The implementation has now been unified for all themes. In general, the message for the most specific matching language tag has the highest priority. If there are both a realm localization message and a Theme 18n message, the realm localization message has the higher priority. Summarized, the priority of the messages is as follows (RL = realm localization, T = Theme i18n files): RL <variant> > T <variant> > RL <region> > T <region> > RL <language> > T <language> > RL en > T en.

Probably this can be better explained with an example: When the variant de-CH-1996 is requested and there is a realm localization message for the variant, this message will be used. If such a realm localization message does not exist, the Theme i18n files are searched for a corresponding message for that variant. If such a message does not exist, a realm localization message for the region (de-CH) will be searched. If such a realm localization message does not exist, the Theme i18n files are searched for a message for that region. If still no message is found, a realm localization message for the language (de) will be searched. If there is no matching realm localization message, the Theme i18n files are be searched for a message for that language. As last fallback, the English (en) translation is used: First, an English realm localization will be searched - if not found, the Theme 18n files are searched for an English message.

UserQueryProvider interface was split into two. One is UserQueryMethodsProvider providing capabilities for querying users. Second one is UserCountMethodsProvider which provides capability for counting number of users in particular storage.

Keycloak now has the ability to differentiate between user storage providers that can efficiently execute count queries and those that cannot. The UserQueryProvider interface still exists and extends both new interfaces. Therefore, there is no need for any modifications in the existing implementations of UserQueryProvider since it retains the same methods.

Starting with this release Keycloak uses a pagination mechanism when querying federated LDAP database. Searching for users should be consistent with search in local database.

Since this release LDAPStorageProvider implements only UserQueryMethodsProvider, not UserQueryProvider.

Starting with this release, we no longer will invest our time on the following Keycloak OpenID Connect Adapters:

This move is already reflected in our documentation and in our quickstart repository. Please, consider looking at the following references for more information:

We recommend starting to look into moving your applications to the alternatives from the references above. Those adapters should not be available anymore in future releases.

The Keycloak JEE SAML Adapter has been discontinued, and we will no longer invest our time on its development following this release.

The official adapter is now based on Jakarta and should be used as soon as you switch your applications to this technology.

This change is already in our documentation and in our quickstart repository. For more information, please consider looking at the following references:

If you cannot migrate your applications to Jakarta, you can still use the "legacy" SAML JEE adapter and still be able to integrate with future releases of the server. However, consider upgrading your applications as soon as possible because we are no longer providing support to JEE.

The preview feature openshift-integration was removed from Keycloak codebase and moved into separate extension. This includes moving of related providers such as custom client storage provider and token review endpoint for Openshift integration.

If you used this feature, you should not use the openshift-integration feature anymore when starting Keycloak server and instead you need to deploy the JAR file from custom extension. You can check the Openshift extension and the instructions in it’s README file for how to deploy the extension to your Keycloak server.

The removal of openshift-integration allows us to remove few third party dependencies from Keycloak distribution. This includes openshift-rest-client, okio-jvm, okhttp, commons-lang, commons-compress, jboss-dmr and kotlin-stdlib. This means that if you use any of these libraries as dependencies of your own providers deployed to Keycloak server, you may also need to copy those jar files explicitly to the Keycloak distribution providers directory as well.

In order to provide a better runtime and leverage as much as possible the underlying stack, all injection points for contextual data using the javax.ws.rs.core.Context annotation were removed. The expected improvement in performance involves no longer creating proxies instances multiple times during the request lifecycle, and drastically reducing the amount of reflection code at runtime.

If you are extending one of the following SPIs:

You should review your custom JAX-RS (sub)resources in order to obtain any contextual data as follows:

If you need access to the current request and response objects, you can now obtain their instances directly from the KeycloakSession:

was replaced by:

In case you have no access to a KeycloakSession instance when invoking a JAX-RS resource method, you can obtain contextual data from the JAX-RS runtime as follows:

Additional contextual data can be obtained from the runtime through the KeycloakContext instance:

If you are extending the server’s REST APIs through the following SPIs:

You need to add an empty META-INF/beans.xml to the JAR file where your custom providers are packaged. Otherwise, they are not recognized by the server at runtime.

If you are using RealmResourceSPI or AdminRealmResourceSpi, you have the choice between adding an empty file named beans.xml under META-INF or annotating the JAX-RS resource classes with the jakarta.ws.rs.ext.Provider annotation.

You should also make sure your JAX-RS methods are declaring the expected media types for input and output by marking them with the @Consumes and @Produces annotations, respectively.

In earlier versions of Keycloak, provider and model interfaces underwent a cleanup process that involved deprecating certain methods. In this release the methods were removed and some additional methods were deprecated. The Javadoc for these methods from Keycloak 21 included information about their corresponding replacements.

Multiple Keycloak CRs may be created in the same namespace and will be managed independently by the operator. To allow for this StatefulSets created by older versions of the operator must be re-created. This will happen automatically when the operator is upgraded and lead to small amount of downtime.

The condition status field was changed from a boolean to a string for conformance with standard Kubernetes conditions. In the CRD it will temporarily be represented as accepting any content, but it will only ever be a string. Please make sure any of your usage of this field is updated to expect the values "True", "False", or "Unknown", rather than true or false.

Keycloak supports the IPv4/IPv6 dual stack and can be accessible by default via the IPv4 and IPv6 addresses. In the older versions of Keycloak, the default approach was to use only IPv4 addresses.

For more details, see Configure Keycloak Server with IPv4 or IPv6.

In the previous version, when Keycloak was used on Java 17 with Javascript providers (Script authenticator, Javascript authorization policy or Script protocol mappers for OIDC and SAML clients), it was needed to copy javascript engine to the distribution. This is no longer needed as Nashorn javascript engine is available in Keycloak server by default. When you deploy script providers, it is recommended to not copy the nashorn script engine and it’s dependencies into the Keycloak distribution.

Default Client ID mapper of Service Account Client has been changed. Token Claim Name field value has been changed from clientId to client_id. client_id claim is compliant with OAuth2 specifications:

clientId userSession note still exists.

Historically it has been possible to create an instance of the Keycloak JS adapter by calling the Keycloak() function directly:

To align this with modern conventions in the JavaScript world it has been possible to use the new operator to create an instance instead:

The function-style constructor has been deprecated for a while, but starting this version we will actively log a deprecation message when it used. This style of constructor will be removed in a future version so make sure to migrate your code to use the new operator.

The terms_and_conditions user attribute was accidentally changed in 21.0.0 to uppercase. This version reverts the user attribute back to lowercase. The value of the attribute is set when accepting Terms and Conditions page.

If any of your custom extensions relies on this attribute, you may need to adjust your code to check both attributes terms_and_conditions and TERMS_AND_CONDITIONS.

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.

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 http://www.w3.org/2000/09/xmldsig#rsa-sha1 or http://www.w3.org/2000/09/xmldsig#dsa-sha1 from the list of "disallowed algorithms" configured on property jdk.xml.dsig.secureValidationPolicy in the file $JAVA_HOME/conf/security/java.security.

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:

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).

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.

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.

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

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.

This release contains the following breaking changes in Keycloak CRs:

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

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.

At Keycloak 18.0.0, the logout is now compatible with the new OIDC specification, which changed the handling for the url parameters. However, to also remain compatible with earlier versions, a compatibility flag is introduced. See the Upgrading Guide for further information for the backwards compatibility option, which allows your application to still use the old format for the url parameters.

While the url parameters can now be configured to be compatible, there was still one incompatibility with keycloak 17 and earlier releases. If the user does not provide a valid idTokenHint, a logout prompt appears instead of a successful logout redirect. Therefore, a new compatibility flag suppress-logout-confirmation-screen is introduced to suppress the logout screen.

You can enable this parameter when you start the server by entering the following command:

With this configuration, you can still use the logout endpoint without a user prompt.

Until now, administrators, which used SAML javascript protocol mapper on their SAML clients or client scopes, were allowed to upload scripts to the server through the Keycloak Administration Console as well as through the RESTful Admin API.

For now on, this capability is disabled and users should deploy scripts directly to the server. This behaviour is aligned with other script based providers. For more details, please take a look at JavaScript Providers.

The new admin console is now the default console in Keycloak. If you are not able to start using the new admin console it is possible to continue to use the old admin console by disabling the new console, by for example running:

An alternative approach to continue using the old admin console is to set the theme for the master realm or any other realm to keycloak.

As the new admin console is significantly different to the old admin console, is now based on React and uses a newer version of PatternFly, any custom themes will most likely have to be re-implemented from scratch. To create a custom theme for the new admin console the theme should extend keycloak.v2 instead of keycloak.

If you have explicitly set the admin console theme to keycloak for the master realm or any other realm, it will continue to use the old admin console. To update to the new admin console you need to change the theme to keycloak.v2.

The old admin console will be removed in Keycloak 21.

Before this release, you would use the --auto-build when running the start command to tell the server to conditionally run a build if any build option has changed prior to starting the server.

In this release, the --auto-build flag is deprecated and you no longer need to use it to indicate that you want to set build options when starting the server. Instead, the server is always going to run a build by default prior to starting the server if any build option has changed. The new behavior improves the overall experience when configuring and starting the server by making it optional, although highly recommended, to run a build command beforehand in order to achieve the best startup time and memory footprint.

Now, in order to achieve the best startup time and memory footprint, set the --optimized option to disable the new default behavior. The --optimized flag tells the server that checking for and running a build directly as part of the startup is not needed:

If you are already using a custom image to set build options and run an optimized Keycloak container, make sure you set the --optimized option when invoking the start command.

For more details, please take a look at the Configuration Guide and the Containers Guide.

Before Keycloak 19.0.0, the quarkus based Keycloak distribution always enabled the following non-application endpoints unintentionally:

Starting in Keycloak 19.0.0, these endpoints are disabled and a request will result in a 404 HTTP status-code. If you are using the /q/…​ endpoints, make sure to change your probes and monitoring systems to use the intended health endpoints instead when upgrading to Keycloak 19.0.0.

The intended health endpoints are:

Apart from disabling the /q/ endpoints, these are the other improvements made to the health endpoints:

Expect more enhancements in this area in the future. For more information, see the Health guide

As stated in the release notes, Keycloak now supports gelf logging for centralized logging systems out of the box.

When you added the gelf related quarkus jars yourself in a prior version, make sure to switch to the supported configuration options in the logging guide and remove your jars from the providers folder.

Keycloak undergoes large refactoring, which impacts existing code. Some of these changes require updates to existing code. These are in more detailed described below.

With this release, we have deprecated podDisruptionBudget field in the Keycloak CR of the legacy Keycloak Operator. This optional field will be ignored when the Operator is deployed on Kubernetes version 1.25 and higher.

As a workaround, you can manually create the Pod Disruption Budget in your cluster, for example:

See also the Kubernetes Documentation.

The new Keycloak Operator now uses StatefulSet instead of Deployment for Keycloak deployments. There’s no automated migration in place given the Operator is a tech preview in this release. If you are using the new Operator with 18.0.z, please make sure to back up, delete and recreate your Keycloak CR after the upgrade to 19.0.0.

Step-up authentication is a new feature. This feature provides the acr client scope, which contains a protocol mapper that is supposed to add the acr claim in the token. The acr claim is not added automatically now as it was before this version, but it is added with the usage of this client scope and protocol mapper.

The client scope is added as a realm "default" client scope and hence will be added to all newly created clients. For performance reasons, the client scope is not automatically added to all existing clients during migration. The clients will not have an acr claim by default after the migration. Consider these possible actions:

Previous versions of Keycloak had supported automatic logout of the user and redirecting to the application by opening logout endpoint URL such as http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri. While that implementation was easy to use, it had potentially negative impact on performance and security. The new version has better support for logout based on the OpenID Connect RP-Initiated Logout specification. The parameter redirect_uri is no longer supported; also, in the new version, the user needs to confirm the logout. It is possible to omit the confirmation and do automatic redirect to the application when you include parameter post_logout_redirect_uri together with the parameter id_token_hint with the ID Token used for login.

The existing deployments are affected in the following ways:

There is a backwards compatibility option, which allows your application to still use the old format of the redirect_uri parameter.

You can enable this parameter when you start the server by entering the following command:

With this configuration, you can still use the format with the redirect_uri parameter. Note the confirmation screen will be needed if the id_token_hint is omitted.

Previous versions of Keycloak had supported managing JavaScript code through the management interfaces like the administrations console and REST API. Starting from this version this is no longer possible, and you should now deploy your scripts to the server in order to configure the following providers:

More details about how to deploy scripts to the server are available in the documentation. Note that to use scripts, you are still required to enable the scripts technology preview feature.

When deploying scripts, the server is going to automatically create their corresponding providers so that you can select them when configuring authentication flows, mappers, and authorization policies.

In general, the steps to update your realms are the following:

The Patternfly (PF) React libraries have been updated, @patternfly/react-core from v3.153.3 to v4.147.0, @patternfly/react-icons from v3.15.16 to v 4.11.8, and @patternfly/react-styles from v3.7.14 to v4.11.8. Several minor UI updates were made to bring the account console into alignment with PF design standards.

Custom developed account UIs might not be compatible with these updates due to the breaking changes in PF. Most breaking changes should be resolvable by updating props on PF components.

Resources:

Components known to have breaking changes:

The metrics-enabled option now only enables the metrics for Keycloak. To enable the readiness and liveness health endpoints, there’s a new boolean option health-enabled. This allows more fine-grained usage of these options, e.g. enabling metrics but not enabling readiness/liveness probes for on-premise use cases. In order to keep the same behaviour as before when metrics-enabled=true was set, you need to additionally set health-enabled=true when building Keycloak.

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:

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.

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:

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 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.

WildFly 25 deprecates the legacy security subsystem that among other things was used to configure TLS. Due to the amount of changes we are not able to provide migration scripts as we have done in the past.

We recommend that rather than copying configuration files from previous versions of Keycloak that you start with the default configuration files provided in Keycloak 16 and apply the relevant changes.

Configuration for the Keycloak subsystem can be copied directly.

For more information around the Elytron subsystem refer to the WildFly documentation.

We are really sorry for this inconvenience and understand this will make it significantly harder for everyone to upgrade to Keycloak 16, but we simply have not been able to find an alternative approach.

One thing worth pointing out is the switch to Quarkus distribution, which we plan to make fully supported in Keycloak 17, will make it significantly easier to configure and upgrade Keycloak.

For more information on WildFly 25 refer to the WildFly 25 release notes.

Keycloak now respects the standard HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables for outgoing HTTP requests. This change could lead to unexpected use of a proxy server if you have for example the HTTP_PROXY variable defined but have no explicit proxy mappings specified in your SPI configuration. To prevent Keycloak from using those environment variables, you can explicitly create a no proxy route for all requests as .*;NO_PROXY.

With this release, we have deprecated and/or marked as unsupported some features in the Keycloak Operator. This concerns the Backup CRD and the operator managed Postgres Database.

Previously, an unsupported metrics extension was added in the example for the creation of the Keycloak CR by the Keycloak Operator. This has been removed.

The Client policies feature was a preview feature since Keycloak 12 and did not have proper support. If you tried this feature and configured some client policies or client profiles in Keycloak 12 or Keycloak 13, then you will need to configure your client policies and client profiles again in the new version. The format of the configuration changed significantly as it was only a preview and hence we do not provide automatic migration of client policies and client profiles created in Keycloak 12 or Keycloak 13.

Manual change is required when the standalone.xml contains references to any of the SmallRye modules. SmallRye modules were removed from the underlying WildFly distribution, and the server does not start if the configuration references them. Thus if the configuration in the standalone.xml refers to these modules, the server configuration migration via migrate-standalone.cli fails before any changes are made to the configuration. In such case, to perform server configuration migration, you have to manually remove all the lines that refer to SmallRye modules. In the default configuration, you need to remove specifically the following lines:

The Keycloak server was upgraded to use Wildfly 23 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

The Keycloak server was upgraded to use Wildfly 22 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

There was added support for the read-only user attributes. This includes the user attributes, which are not supposed to be edited by the user or by the administrator when updating user with REST API or with the Keycloak user interfaces. It can be important especially if you use:

See the details in the Threat model mitigation chapter.

If you use the OpenID Connect parameter request_uri, a requirement exists that your client needs to have Valid Request URIs configured. This can be configured through the admin console on the client details page or through the admin REST API or client registration API. Valid Request URIs need to contain the list of Request URI values, which are permitted for the particular client. This is to avoid SSRF attacks. There is possibility to use wildcards or relative paths similarly such as the Valid Redirect URIs option, however for security purposes, we typically recommend to use as specific value as possible.

The Keycloak server was upgraded to use Wildfly 22 as the underlying container. This does not directly involve any specific Keycloak server functionality, but a few changes related to the migration, which are worth mentioning.

The Keycloak server was upgraded to use Wildfly 21 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

No user session is created after successful authentication with the Docker protocol. For details, please refer to the Server Administration Guide.

The Keycloak login theme components have been upgraded to PatternFly 4. The old PatternFly 3 runs simultaneously with the new one, so it’s possible to keep PF3 components. However, some changes to the design of the login theme were performed. Please upgrade your custom login theme due them. An example with the necessary changes can be found in the keycloak/examples/themes/theme/sunrise directory. No additional setup is required.

From this Keycloak version, the OAuth2 Client Credentials Grant endpoint does not issue refresh tokens by default. This behavior is aligned with the OAuth2 specification. As a side effect of this change, no user session is created on the Keycloak server side after successful Client Credentials authentication, which results in improved performance and memory consumption. Clients that use Client Credentials Grant are encouraged to stop using refresh tokens and instead always authenticate at every request with grant_type=client_credentials instead of using refresh_token as grant type. In relation to this, Keycloak has support for revocation of access tokens in the OAuth2 Revocation Endpoint, hence clients are allowed to revoke individual access tokens if needed.

For backwards compatibility, a possibility to stick to the behavior of old versions exists. When this is used, the refresh token will be still issued after a successful authentication with the Client Credentials Grant and also the user session will be created. This can be enabled for the particular client in the Keycloak admin console, in client details in the section with OpenID Connect Compatibility Modes with the switch Use Refresh Tokens For Client Credentials Grant.

The Keycloak server was upgraded to use Wildfly 20 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

In the previous Keycloak version, when the LDAP provider was configured with Import Users OFF, it was possible to update the user even if some of non-LDAP mapped attributes were changed. This situation resulted in confusing behavior, when the attribute appeared to be updated, but it was not. In the current version, the update is not allowed to be performed at all if any non-LDAP mapped attributes are changed.

This should not affect most of the deployments, but some can be affected under some rare circumstances. For example if you previously tried to update a user with the admin REST API and the user had some incorrect attribute changes, the update was possible. With the current version, the update is not possible and you will be immediately informed about the reason.

The fields username, email, firstName and lastName in the UserModel are migrated to custom attributes as a preparation for adding more sophisticated user profiles to Keycloak in an upcoming version. If a database contains users with custom attributes of that exact name, the custom attributes will need to be migrated before upgrading. This migration does not occur automatically. Otherwise, they will not be read from the database anymore and possibly deleted. This situation implies that the username can now also be accessed and set via UserModel.getFirstAttribute(UserModel.USERNAME). Similar implications exist for other fields. Implementers of SPIs subclassing the UserModel directly or indirectly should ensure that the behavior between setUsername and setSingleAttribute(UserModel.USERNAME, …​) (and similar for the other fields) is consistent. Users of the policy evaluation feature have to adapt their policies if they use the number of attributes in their evaluations since every user will now have four new attributes by default.

The public API of UserModel did not change. No changes to frontend resources or SPIs accessing user data are necessary. Also, the database did not change yet.

Instagram IdP now uses new API as the old legacy API was deprecated. This requires getting new API credentials. For details, please refer to the Server Administration Guide.

Special attention is required for existing users that use Instagram IdP, specially the ones for whom it is the only authentication option. Such users have to log in to Keycloak using Instagram IdP before September 30th, 2020. After that day they’ll have to use a different authentication method (like password) to log in to manually update their Instagram social link, or create a new account in Keycloak. This is because Instagram user IDs are not compatible between the old and new API, however the new API temporarily returns both new and old user IDs to allow migration. Keycloak automatically migrates the ID once user logs in.

In previous versions, Keycloak advertised two introspection endpoints: token_introspection_endpoint and introspection_endpoint. The latter is the one defined by RFC-8414. The former, previously deprecated, has now been removed.

It is no longer necessary to set promiseType in the JavaScript adapter, and both are available at the same time. It is recommended to update applications to use native promise API (then and catch) as soon as possible, as the legacy API (success and error) will be removed at some point.

Version 9.0.1 fixes a problem which could create duplicated top level groups in the realm. Nevertheless the existence of previous duplicated groups makes the upgrade process fail. The Keycloak server can be affected by this issue if it is using an H2, MariaDB, MySQL or PostgreSQL database. Before launching the upgrade, check if the server contains duplicated top level groups. For example the following SQL query can be executed at database level to list them:

Only one top level group can exist in each realm with the same name. Duplicates should be reviewed and deleted before the upgrade. The error in the upgrade contains the message Change Set META-INF/jpa-changelog-9.0.1.xml::9.0.1- KEYCLOAK-12579-add-not-null-constraint::keycloak failed.

A number of improvements have been made to how the locale for the login page is selected, as well as when the locale is updated for a user.

See the Server Administration Guide for more details.

In the year 2038 an int is no longer able to hold the value of seconds since 1970, as such we are working on updating these to long values. Moreover, another issue related with processing of int values exists in token representation. An int will by default result into 0 in the JSON representation, while it should not be included.

See JavaDocs for further details on exact methods that have been deprecated and replacement methods.

The old request and fixed hostname providers are replaced with a new default hostname provider. The request and fixed hostname providers are now deprecated and it is recommended to switch to the default hostname provider as soon as possible.

The Keycloak server was upgraded to use Wildfly 18 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

Until now, administrators were allowed to upload scripts to the server through the Keycloak Administration Console as well as through the RESTful Admin API.

For now on, this capability is disabled by default and users should prefer to deploy scripts directly to the server. For more details, please take a look at JavaScript Providers.

In the previous releases, developers were allowed to provide client credentials to the JavaScript adapter. For now on, this capability was removed, because client-side apps are not safe to keep secrets.

We did some refactoring and improvements related to the authentication flows, which requires some attention during migration.

We added more flexibility around storing of user credentials. Among other things, every user can have multiple credentials of the same type, for example multiple OTP credentials. As a result, some changes to the database schema were performed. However the credentials from the previous version should be automatically updated to the new format and users should be still able to login with their passwords or OTP credentials set in the previous version.

The Keycloak server was upgraded to use Wildfly 17 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

The Keycloak server was upgraded to use Wildfly 16 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

We have added a new microprofile-jwt optional client scope to handle the claims defined in the MicroProfile/JWT Auth Specification. This new client scope defines protocol mappers to set the username of the authenticated user to the upn claim and to set the realm roles to the groups claim.

We have added a new switch in the OIDC identity provider configuration named Accepts prompt=none forward from client to identify IDPs that are able to handle forwarded requests that include the prompt=none query parameter.

Until now, when receiving an auth request with prompt=none a realm would return a login_required error if the user is not authenticated in the realm without checking if the user has been authenticated by an IDP. From now on, if a default IDP can be determined for the auth request (either by the use of the kc_idp_hint query param or by setting up a default IDP for the realm) and if the Accepts prompt=none forward from client switch has been enabled for the IDP, the auth request is forwarded to the IDP to check if the user has been authenticated there.

It is important to note that this switch is only taken into account if a default IDP is specified, in which case we know where to forward the auth request without having to prompt the user to select an IDP. If a default IDP cannot be determined we cannot assume which one will be used to fulfill the auth request so the request forwarding is not performed.

The Keycloak server was upgraded to use Wildfly 15 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

The Google Identity Provider implementation in Keycloak up to version 4.8.1 relies on the Google+ API endpoints for authorization and obtaining the user profile. From March 2019 onwards, Google is removing support for the Google+ API in favor of the new Google Sign-in authentication system. The Keycloak identity provider has been updated to use the new endpoints so if this integration is in use make sure you upgrade to Keycloak version 4.8.2 or later.

If you run into an error saying that the application identifier was not found in the directory, you will have to register the client application again in the Google API Console portal to obtain a new application id and secret.

It is possible that you will need to adjust custom mappers for non-standard claims that were provided by Google+ user information endpoint and are provided under different name by Google Sign-in API. Please consult Google documentation for the most up-to-date information on available claims.

Accordingly with LinkedIn, all developers need to migrate to version 2.0 of their APIs and OAuth 2.0. As such, we have updated our LinkedIn Social Broker.

Existing deployments using this broker may start experiencing errors when fetching user’s profile using version 2 of LinkedIn APIs. This error may be related with the lack of permissions granted to the client application used to configure the broker which may not be authorized to access the Profile API or request specific OAuth2 scopes during the authentication process.

Even for newly created LinkedIn client applications, you need to make sure that the client is able to request the r_liteprofile and r_emailaddress OAuth2 scopes, at least, as well that the client application can fetch current member’s profile from the https://api.linkedin.com/v2/me endpoint.

Due to these privacy restrictions imposed by LinkedIn in regards to access to member’s information and the limited set of claims returned by the current member’s Profile API, the LinkedIn Social Broker is now using the member’s email address as the default username. That means that the r_emailaddress is always set when sending authorization requests during the authentication.

We have added new realm default client scopes roles and web-origins. These client scopes contain protocol mappers to add the roles of the user and allowed web origins to the token. During migration, these client scopes should be automatically added to all the OpenID Connect clients as default client scopes. Hence no setup should be required after database migration is finished.

To use native JavaScript promise with the JavaScript adapter it is now required to set promiseType to native in the init options.

In the past if native promise was available a wrapper was returned that provided both the legacy Keycloak promise and the native promise. This was causing issues as the error handler was not always set prior to the native error event, which resulted in Uncaught (in promise) error.

The Microsoft Identity Provider implementation in Keycloak up to version 4.5.0 relies on the Live SDK endpoints for authorization and obtaining the user profile. From November 2018 onwards, Microsoft is removing support for the Live SDK API in favor of the new Microsoft Graph API. The Keycloak identity provider has been updated to use the new endpoints so if this integration is in use make sure you upgrade to Keycloak version 4.6.0 or later.

Legacy client applications registered under "Live SDK applications" won’t work with the Microsoft Graph endpoints due to changes in the id format of the applications. If you run into an error saying that the application identifier was not found in the directory, you will have to register the client application again in the Microsoft Application Registration portal to obtain a new application id.

The Keycloak server was upgraded to use Wildfly 14 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

The Keycloak server was upgraded to use Wildfly 13 as the underlying container. This does not directly involve any specific Keycloak server functionality, however, note these changes related to migration:

In previous versions it was recommended to use a filter to specify permitted hostnames. It is now possible to set a fixed hostname which makes it easier to make sure the valid hostname is used and also allows internal applications to invoke Keycloak through an alternative URL, for example an internal IP address. It is recommended that you switch to this approach in production.

We added support for Client Scopes, which requires some attention during migration.

We added support for UMA 2.0. This version of the UMA specification introduced some important changes on how permissions are obtained from the server.

Here are the main changes introduced by UMA 2.0 support. See Authorization Services Guide for details.

The OpenID Connect Session Management specification requires that the parameter session_state is present in the OpenID Connect Authentication Response.

In past releases, we did not have this parameter, but now Keycloak adds this parameter by default, as required by the specification.

However, some OpenID Connect / OAuth2 adapters, and especially older Keycloak adapters, may have issues with this new parameter.

For example, the parameter will be always present in the browser URL after successful authentication to the client application. In these cases, it may be useful to disable adding the session_state parameter to the authentication response. This can be done for the particular client in the Keycloak admin console, in client details in the section with OpenID Connect Compatibility Modes, described in Compatibility with older adapters. Dedicated Exclude Session State From Authentication Response switch exists, which can be turned on to prevent adding the session_state parameter to the Authentication Response.

We’ve added two new password hashing algorithms (pbkdf2-sha256 and pbkdf2-sha512). New realms will use the pbkdf2-sha256 hashing algorithm with 27500 hashing iterations. Since pbkdf2-sha256 is slightly faster than pbkdf2 the iterations was increased to 27500 from 20000.

Existing realms are upgraded if the password policy contains the default value for hashing algorithm (not specified) and iteration (20000). If you have changed the hashing iterations you need to manually change to pbkdf2-sha256 if you’d like to use the more secure hashing algorithm.

OpenID Connect specification requires that parameter scope with value openid is used in initial authorization request. So in Keycloak 2.1.0 we changed our adapters to use scope=openid in the redirect URI to Keycloak. Now we changed the server part too and ID token will be sent to the application just if scope=openid is really used. If it’s not used, then ID token will be skipped and just Access token and Refresh token will be sent to the application. This also allows that you can omit the generation of ID Token on purpose - for example for space or performance purposes.

Direct grants (OAuth2 Resource Owner Password Credentials Grant) and Service accounts login (OAuth2 Client credentials grant) also don’t use ID Token by default now. You need to explicitly add scope=openid parameter to have ID Token included.

We are working on support for multiple datacenters. As the initial step, we introduced authentication session and action tokens. Authentication session replaces Client session, which was used in previous versions. Action tokens are currently used especially for the scenarios, where the authenticator or requiredActionProvider requires sending email to the user and requires user to click on the link in email.

Here are concrete changes related to this, which may affect you for the migration.

First change related to this is introducing new Infinispan caches authenticationSessions and actionTokens in standalone.xml or standalone-ha.xml. If you use our migration CLI, you don’t need to care much as your standalone(-ha).xml files will be migrated automatically.

Second change is changing of some signatures in methods of authentication SPI. This may affect you if you use custom Authenticator or RequiredActionProvider. Classes AuthenticationFlowContext and RequiredActionContext now allow to retrieve authentication session instead of client session.

We also added some initial support for sticky sessions. You may want to change your load balancer/proxy server and configure it if you don’t want to suffer from it and want to have better performance. The route is added to the new AUTH_SESSION_ID cookie. More info in the clustering documentation.

Another change is, that token.getClientSession() was removed. This may affect you for example if you’re using Client Initiated Identity Broker Linking feature.

The ScriptBasedAuthenticator changed the binding name from clientSession to authenticationSession, so you would need to update your scripts if you’re using this authenticator.

Finally we added some new timeouts to the admin console. This allows you for example to specify different timeouts for the email actions triggered by admin and by user himself.

If you migrate from version 2.2.0 or older and you used offline tokens, then your offline tokens didn’t have KID in the token header. We added KID to the token header in 2.3.0 together with the ability to have multiple realm keys, so Keycloak is able to find the correct key based on the token KID.

For the offline tokens without KID, Keycloak 2.5.1 will always use the active realm key to find the proper key for the token verification. In other words, migration of old offline tokens will work. So for example, your user requested offline token in 1.9.8, then you migrate from 1.9.8 to 2.5.1 and then your user will be still able to refresh his old offline token in 2.5.1 version.

But a limitation exists. Once you change the realm active key, the users won’t be able to refresh old offline tokens anymore. So you shouldn’t change the active realm key until all your users with offline tokens refreshed their tokens. Obviously newly refreshed tokens will have KID in the header, so after all users exchange their old offline tokens, you are free to change the active realm key.

The realms cache defined in the infinispan subsystem in standalone.xml or standalone-ha.xml configuration file, now has the eviction with the 10000 records by default. This is the same default as the users cache.

Also the authorization cache now doesn’t have any eviction on it by default.

The keycloak-server-spi module has been split into keycloak-server-spi and keycloak-server-spi-private. APIs within keycloak-server-spi will not change between minor releases, while we reserve the right and may quite likely change APIs in keycloak-server-spi-private between minor releases.

Key in SAML assertions and documents are now encrypted using RSA-OAEP encryption scheme. If you want to use encrypted assertions, make sure that service providers understand this encryption scheme. In the unlikely case that SP would not be able to handle the new scheme, Keycloak can be made to use legacy RSA-v1.5 encryption scheme when started with system property keycloak.saml.key_trans.rsa_v1.5 set to true.

Even if you use Keycloak in cluster, the caches realms and users defined in infinispan subsystem in standalone-ha.xml are always local caches now. A separate cache work exists, which handles sending invalidation messages between cluster nodes and informing whole cluster what records in underlying realms and users caches should be invalidated.

All Admin REST API endpoints that support pagination now have a default max results set to 100. If you want to return more than 100 entries you need to explicitly specify that with ?max=<RESULTS>.

In 2.3.0 release we added support for Public Key Rotation. When admin rotates the realm keys in Keycloak admin console, the Client Adapter will be able to recognize it and automatically download new public key from Keycloak. However this automatic download of new keys is done just if you don’t have realm-public-key option in your adapter with the hardcoded public key. For this reason, we don’t recommend to use realm-public-key option in adapter configuration anymore.

Note this option is still supported, but it may be useful just if you really want to have hardcoded public key in your adapter configuration and never download the public key from Keycloak. In theory, one reason for this can be to avoid man-in-the-middle attack if you have untrusted network between adapter and Keycloak, however in that case, it is much better option to use HTTPS, which will secure all the requests between adapter and Keycloak.

In this release, we added new cache keys to the infinispan subsystem, which is defined in standalone.xml or standalone-ha.xml configuration file. It has also some eviction and expiration defined. This cache is internally used for caching the external public keys of the entities trusted by the server (Identity providers or clients, which uses authentication with signed JWT).

The databaseSchema property for both JPA and Mongo is now deprecated and is replaced with initializeEmpty and migrationStrategy. initializeEmpty can bet set to true or false and controls if an empty database should be initialized. migrationStrategy can be set to update, validate and manual. manual is only supported for relational databases and will write an SQL file with the required changes to the database schema. Please note that for Oracle database, the created SQL file contains SET DEFINE OFF command understood by Oracle SQL clients. Should the script be consumed by any other client, please replace the lines with equivalent command of the tool of your choice that disables variable expansion or remove it completely if such functionality is not applicable.

The following scenarios are affected:

Identity providers no longer has an option to set it as a default authentication provider. Instead go to Authentication, select the Browser flow and configure the Identity Provider Redirector. It has an option to set the default identity provider.

Upgrading from 1.0.0.Final is no longer supported. To upgrade to this version upgrade to 1.9.8.Final prior to upgrading to 2.0.0.

The default password hashing interval for new realms has been increased to 20K (from 1 previously). This change will have an impact on performance when users authenticate. For example with the old default (1) it takes less than 1 ms to hash a password, but with the new default (20K) the same operation can take 50-100 ms.

The script to add admin users to Keycloak has been renamed to add-user-keycloak.

We’ve removed the option auth-server-url-for-backend-requests due to issues in some scenarios when it was used. In more details, it was possible to access the Keycloak server from 2 different contexts (internal and external), which was causing issues in token validations etc.

If you still want to use the optimization of network, which this option provided (avoid the application to send backchannel requests through load balancer but send them to local Keycloak server directly) you may need to handle it at hosts configuration (DNS) level.

We’ve moved the themes and providers directories from standalone/configuration/themes and standalone/configuration/providers to themes and providers respectively. If you have added custom themes and providers you need to move them to the new location. You also need to update keycloak-server.json as it’s changed due to this.

Previously, if you had installed our SAML or OIDC Keycloak subsystem adapters into WildFly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application regardless if you were using Keycloak or not. These libraries are now only added to your deployment if you have Keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml)

The Client Registration service endpoints have been moved from {realm-name}/clients to {realm-name}/clients-registrations.