Upgrading Guide

To enable automatic upgrading of the database schema, set the migration-strategy property value to "update" for the default connections-jpa provider:

When you start the server with this setting your database is automatically migrated if the database schema has changed in the new version.

Creating an index on huge tables with millions of records can easily take a huge amount of time and potentially cause major service disruption on upgrades. For those cases, we added a threshold (the number of records) for automated index creation. By default, this threshold is 300000 records. When the number of records is higher than the threshold, the index is not created automatically, and there will be a warning message in server logs including SQL commands which can be applied later manually.

To change the threshold, set the index-creation-threshold property, value for the default connections-liquibase provider:

To enable manual upgrading of the database schema, set the migration-strategy property value to "manual" for the default connections-jpa provider:

When you start the server with this configuration it checks if the database needs to be migrated. The required changes are written to an SQL file that you can review and manually run against the database. For further details on how to apply this file to the database, see the documentation for the relational database you’re using. After the changes have been written to the file, the server exits.

If you have customized any of the templates you need to carefully review the changes that have been made to the templates to decide if you need to apply these changes to your customized templates. Most likely you will need to apply the same changes to your customized templates. If you have not customized any of the listed templates you can skip this section.

A best practice is to use a diff tool to compare the templates to see what changes you might need to make to your customized template. If you have only made minor changes it is simpler to compare the updated template to your customized template. However, if you have made many changes it might be easier to compare the new template to your customized old template, as this will show you what changes you need to make.

The following screenshot compares the info.ftl template from the Login theme and an example custom theme:

From this comparison it is easy to identify that the first change (Hello world!!) was a customization, while the second change (if pageRedirectUri) is a change to the base theme. By copying the second change to your custom template, you have successfully updated your customized template.

For the alternative approach the following screenshot compares the info.ftl template from the old installation with the updated info.ftl template from the new installation:

From this comparison it is easy to identify what has been changed in the base template. You will then manually have to make the same changes to your modified template. Since this approach is not as simple as the first approach, only use this approach if the first one is not feasible.

If you have added support for another language, you need to apply all the changes listed above. If you have not added support for another language, you might not need to change anything; you only have to make changes if you have changed an affected message in your theme.

For added values, review the value of the message in the base theme to determine if you need to customize that message.

For renamed keys, rename the key in your custom theme.

For changed values, check the value in the base theme to determine if you need to make changes to your custom theme.

If you are inheriting styles from the keycloak or rh-sso themes you might need to update your custom styles to reflect changes made to the styles from the built-in themes.

A best practice is to use a diff tool to compare the changes to stylesheets between the old server installation and the new server installation.

For example, using the diff command:

Review the changes and determine if they affect your custom styling.

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

In the OpenID Connect authentication response we used to return the session state as session-state this is not correct according to the specification and has been renamed to session_state.

In 1.2 we deprecated a number of endpoints that where not consistent with the OpenID Connect specifications, these have now been removed. This also applies to the validate token endpoint that is replaced with the new introspect endpoint in 1.8.

Feedback in template.ftl has been moved and format has changed slightly.

Most of our modules and source code have been consolidated into two maven modules: keycloak-server-spi and keycloak-services. SPI interfaces are in server-spi, implementations are in keycloak-services. All JPA dependent modules have been consolidated under keycloak-model-jpa. Same goes with mongo and Infinispan under modules keycloak-model-mongo and keycloak-model-infinispan.

To plug a security attack vector, for platforms that support it (Tomcat 8, Undertow/WildFly, Jetty 9), the Keycloak OIDC and SAML adapters will change the session id after login. You can turn off this behavior check adapter config switches.

Keycloak SAML SP Client adapter now requires a specific endpoint, /saml to be registered with your IDP.

In previous releases we shipped with a default admin user with a default password, this has now been removed. If you are doing a new installation of 1.8 you will have to create an admin user as a first step.

In order to add more compliance with OAuth2 specification, we added a new endpoint for token introspection. The new endpoint can reached at /realms/{realm-name}/protocols/openid-connect/token/introspect and it is solely based on RFC-7662.

The /realms/{realm-name}/protocols/openid-connect/validate endpoint is now deprecated and we strongly recommend you to move to the new introspection endpoint as soon as possible. The reason for this change is that RFC-7662 provides a more standard and secure introspection endpoint.

The new token introspection URL can now be obtained from OpenID Connect Provider’s configuration at /realms/{realm-name}/.well-known/openid-configuration. There you will find a claim with name token_introspection_endpoint within the response. Only confidential clients are allowed to invoke the new endpoint, where these clients will be usually acting as a resource server and looking for token metadata in order to perform local authorization checks.

In order to add more compliance with OpenID Connect specification, we added flags into admin console to Client Settings page, where you can enable/disable various kinds of OpenID Connect/OAuth2 flows (Standard flow, Implicit flow, Direct Access Grants, Service Accounts). As part of this, we have Direct Access Grants (corresponds to OAuth2 Resource Owner Password Credentials Grant) disabled by default for new clients.

Clients migrated from previous version have Direct Access Grants enabled just if they had flag Direct Grants Only on. The Direct Grants Only flag was removed as if you enable Direct Access Grants and disable both Standard+Implicit flow, you will achieve same effect.

We also added built-in client admin-cli to each realm. This client has Direct Access Grants enabled. So if you’re using Admin REST API or Keycloak admin-client, you should update your configuration to use admin-cli instead of security-admin-console as the latter one doesn’t have direct access grants enabled anymore by default.

In this version, we added First Broker Login, which allows you to specify what exactly should be done when new user is logged through Identity provider (or Social provider), but no Keycloak user linked to the social account exists yet. As part of this work, we added option First Login Flow to identity providers where you can specify the flow and then you can configure this flow under Authentication tab in admin console.

We also removed the option Update Profile On First Login from the Identity provider settings and moved it to the configuration of Review Profile authenticator. So once you specify which flow should be used for your Identity provider (by default it’s First Broker Login flow), you go to Authentication tab, select the flow and then you configure the option under Review Profile authenticator.

form-error-page in web.xml will no longer work for client adapter authentication errors. You must define an error-page for the various HTTP error codes. See documentation for more details if you want to catch and handle adapter error conditions.

The interface itself and method signatures did not change. However some changes in the behavior exist. We added First Broker Login flow in this release and the method IdentityProviderMapper.importNewUser is now called after First Broker Login flow is finished. So if you want to have any attribute available in Review Profile page, you would need to use the method preprocessFederatedIdentity instead of importNewUser . You can set any attribute by invoke BrokeredIdentityContext.setUserAttribute and that will be available on Review profile page.

Old versions of Keycloak allowed reusing refresh tokens multiple times. Keycloak still permits this, but also have an option Revoke refresh token to disallow it. Option is under token settings in admin console. When a refresh token is used to obtain a new access token a new refresh token is also included. When option is enabled, then this new refresh token should be used next time the access token is refreshed. It won’t be possible to reuse old refresh token multiple times.

We did a bit of restructure and renamed some packages. It is mainly about renaming internal packages of util classes. The most important classes used in your application ( for example AccessToken or KeycloakSecurityContext ) as well as the SPI are still unchanged. However, a slight chance exists that you will be affected and will need to update imports of your classes. For example if you are using multitenancy and KeycloakConfigResolver, you will be affected as for example class HttpFacade was moved to different package - it is org.keycloak.adapters.spi.HttpFacade now.

We added support for offline tokens in this release, which means that we are persisting "offline" user sessions into database now. If you are not using offline tokens, nothing will be persisted for you, so you don’t need to care about worse performance for more DB writes. However in all cases, you will need to update standalone/configuration/keycloak-server.json and add userSessionPersister like this:

If you want sessions to be persisted in Mongo instead of classic RDBMS, use provider mongo instead.

Infinispan is now the default and only realm and user cache providers. In non-clustered mode a local Infinispan cache is used. We’ve also removed our custom in-memory cache and the no cache providers. If you have realmCache or userCache set in keycloak-server.json to mem or none please remove these. As Infinispan is the only provider the realmCache and userCache objects are no longer needed and can be removed.

Infinispan is now the default and only user session provider. In non-clustered mode a local Infinispan cache is used. We’ve also removed the JPA and Mongo user session providers. If you have userSession set in keycloak-server.json to mem, jpa or mongo please remove it. As Infinispan is the only provider the userSession object is no longer needed and can be removed.

For anyone that wants to achieve increased durability of user sessions this can be achieved by configuring the user session cache with more than one owner or use a replicated cache. It’s also possible to configure Infinispan to persist caches, although that would have impacts on performance.

In the default theme we have now removed the contact details from the registration page and account management. The admin console now lists all the users attributes, not just contact specific attributes. The admin console also has the ability to add/remove attributes to a user. If you want to add contact details, please refer to the address theme included in the examples.

In the past Direct Grant API (or Resource Owner Password Credentials) was disabled by default and an option to enable it on a realm existed. The Direct Grant API is now always enabled and the option to enable/disable for a realm is removed.

There are again few database changes. Remember to back up your database prior to upgrading.

There are few minor changes in UserFederationProvider interface. You may need to sync your implementation when upgrade to newer version and upgrade few methods, which has changed signature. Changes are really minor, but were needed to improve performance of federation.

Following on from the distribution changes that was done in the last release the standalone download of Keycloak is now based on WildFly 9.0.0.Final. This also affects the overlay which can only be deployed to WildFly 9.0.0.Final or JBoss EAP 6.4.0.GA. WildFly 8.2.0.Final is no longer supported for the server.

There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7:

Make sure you grab the correct one.

You also need to update standalone.xml as the extension module and subsystem definition has changed. See Securing Applications and Services Guide for details.

Keycloak is now available in 3 downloads: standalone, overlay and demo bundle. The standalone is intended for production and non-JEE developers. Overlay is aimed at adding Keycloak to an existing WildFly 8.2 or EAP 6.4 installation and is mainly for development. Finally we have a demo (or dev) bundle that is aimed at developers getting started with Keycloak. This bundle contains a WildFly server, with Keycloak server and adapter included. It also contains all documentation and examples.

This release contains again a number of changes to the database. The biggest one is Application and OAuth client merge. Remember to back up your database prior to upgrading.

Application and OAuth clients are now merged into Clients. The UI of admin console is updated and database as well. Your data from database should be automatically updated. The previously set Applications will be converted into Clients with Consent required switch off and OAuth Clients will be converted into Clients with this switch on.

This release contains a number of changes to the database. Remember to back up your database prior to upgrading.

The value of iss claim in access and id tokens have changed from realm name to realm url. This is required by OpenID Connect specification. If you’re using our adapters no change is required, except if you’ve been using bearer-only without specifying the auth-server-url, you have to add it now. If you’re using another library (or RSATokenVerifier) you need to make the corresponding changes when verifying iss.

To comply with OpenID Connect specification the authentication and token endpoints have been changed to having a single authentication endpoint and a single token endpoint. As per-spec response_type and grant_type parameters are used to select the required flow. The old endpoints (/realms/{realm-name}/protocols/openid-connect/login, /realms/{realm-name}/protocols/openid-connect/grants/access, /realms/{realm-name}/protocols/openid-connect/refresh, /realms/{realm-name}/protocols/openid-connect/access/codes) are now deprecated and will be removed in a future version.

The layout of themes has changed. The directory hierarchy used to be type/name this is now changed to name/type. For example a login theme named sunrise used to be deployed to standalone/configuration/themes/login/sunrise, which is now moved to standalone/configuration/themes/sunrise/login. This change was done to make it easier to have groups of the different types for the same theme into one folder.

If you deployed themes as a JAR in the past you had to create a custom theme loader which required Java code. This has been simplified to only requiring a plain text file (META-INF/keycloak-themes.json) to describe the themes included in a JAR.

Previously a dedicated Claims tab existed in the admin console for application and OAuth clients. This was used to configure which attributes should go into access token for particular application/client. This was removed and is replaced with protocol mappers which are more flexible.

You don’t need to care about migration of database from previous version. We did migration scripts for both RDBMS and Mongo, which should ensure that claims configured for particular application/client will be converted into corresponding protocol mappers (Still it’s safer to back up DB before migrating to newer version though). Same applies for exported JSON representation from previous version.

We refactored social providers SPI and replaced it with Identity Brokering SPI, which is more flexible. The Social tab in admin console is renamed to Identity Provider tab.

Again you don’t need to care about migration of database from previous version similarly like for Claims/protocol mappers. Both configuration of social providers and "social links" to your users will be converted to corresponding Identity providers.

Only required action from you would be to change allowed Redirect URI in the admin console of particular 3rd party social providers. You can first go to the Keycloak admin console and copy Redirect URI from the page where you configure the identity provider. Then you can simply paste this as allowed Redirect URI to the admin console of 3rd party provider (IE. Facebook admin console).