Skip to content

How upgrades are handled ​

One of the key of security, is to keep the software up-to-date to avoid exploit of known issues. The team is responsible for keeping the underlying infrastructure secured and up to date.

Cloud-IAM follows the Keycloak release cycle and keeps your deployments up-to-date. Every time Keycloak releases a new version, our QA team check that the new version is fully functional with all our processes. Once ready, the new version is available to our customer.

Steps ​

As minor versions are usually bug or security fixes, minor version upgrades without impact are applied without notice by the Cloud-IAM support team. Those upgrades are seamless in the end-user point of view.

To help the diagnosis in case an upgrade introduced an issue with your deployment, the deployment can only be upgraded one major version at a time.

How are planned the upgrades ​

Little Lemur plans (Free) ​

For freemium, the instance is shared across multiple deployments. The servers are upgraded without notice.

Dedicated plans ​

For dedicated plans, the upgrade are always planned with the customer. Most of the time, the version upgrades are seamless, thanks to our deployment process 👌.

However, Keycloak versions are not always backward compatible. In such cases, there is no other solution than stopping completely the cluster for a very few minutes. The usual downtime is less than 5 minutes between the last node has been stopped, and the first has restarted.

Of course, the customers are noticed about theses impacts so the Cloud-IAM Ops team can schedule the migration at the best maintenance window.

Keycloak upgrade process ​

To let the customers plan the upgrade and some internal qualification or development, the Cloud team publishes a schedule of the next versions deprecation.

VersionRelease dateDeprecation at Cloud-IAMRelease note
Keycloak 15.x WildflyAugust 2021end of January 2023link
Keycloak 16.x WildflyDecember 2021end of February 2023link
Keycloak 17.x WildflyFebruary 2022end of February 2023link
Keycloak 18.x WildflyApril 2022end of March 2023link
Keycloak 18.x Quarkus 2.xApril 2022end of June 2023link
Keycloak 19.x Quarkus 2.xAugust 2022end of September 2023link
Keycloak 20.x Quarkus 2.xNovember 2022end of November 2023link
Keycloak 21.x Quarkus 2.xApril 2023end of April 2024link
Keycloak 22.x Quarkus 3.xJuly 2023end of July 2024link
Keycloak 23.x Quarkus 3.xDecember 2023end of December 2024link
Keycloak 24.x Quarkus 3.xMarch 2024end of March 2025link
Keycloak 25.x Quarkus 3.xJune 2024end of June 2025link


Customer are welcomed to ask the Cloud-IAM support team to upgrade to the latest versions without waiting for the deprecation deadline

Migrating to 16.x Wildfly ​

This version is mostly related to Wildfly upgrade. Nothing is related to the change of SPI in this version.

Migrating to 17.x Wildfly ​

This version is mostly related to the introduction of Quarkus. Nothing is related to the change of SPI in this version.

Migrating to 18.x Wildfly ​

The deprecated upload-script feature was removed. This feature was deprecated for a long time and has finally been removed.

If you are using any of these capabilities:

  • OpenID Connect Script Mapper
  • Script Authenticator (Authentication Execution)
  • JavaScript Policies

Then you should read this document to migrate the feature:

The OpenID Connect Logout has also been reviewed and do not support anymore the redirect_uri parameter. Checkout the documentation to understand the new behavior.

Migrating to 18.x Quarkus ​

The core of Keycloak remain exactly the same between the Wildfly and the Quarkus version. However, prior to Quarkus, it was possible to package custom extensions as ear or war and to upload them into Keycloak. From this version, only jar can be uploaded and will deploy.


Cloud-IAM sets the KC_HTTP_RELATIVE_PATH=/auth environment variable to remain compatible with existing configuration

Migrating to 19.x ​

Several changes in the Keycloak SPI have been made. Check the changes described here. The methods are deprecated but are meant to remain compatible for this version.

We encourage testing the extensions in a Keycloak v19.x Quarkus before upgrading to this version.

There has been a change with the /auth/realms//protocol/openid-connect/userinfo endpoint to comply with RFC (changelog) The error handling has been remodeled and, the most notable change is that if the token does not have the openid scope, the endpoint will return a 403.

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="my-realm", error="insufficient_scope", error_description="Missing openid scope"
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="my-realm", error="insufficient_scope", error_description="Missing openid scope"

Check if the applications are using this endpoint and ensure the scope of the tokens are properly configured.

Migrating to 20.x ​

Deprecated methods from the models were removed. Checkout the list of updated interfaces.

We encourage testing the extensions in a Keycloak v20.x Quarkus before upgrading to this version.

Migrating to 21.x ​

The old admin console is removed and could not be restored. Therefore, admin theme based on the old console won't work anymore.

Keycloak changed the metric collection library to micrometer. This has an impact on the Cloud-IAM metrics reported by deployment. The change is not backward compatible because the metrics have be renamed according to the micrometer naming conventions.

Also note that the underlying libraries used to synchronize the Keycloak caches are not compatible. Therefore, the user sessions are lost during the upgrade and this implies the user have to reconnect after the migration.

From this version, the custom extensions can be compiled against Java 17.

Migrating to 22.x ​

This version of Keycloak transitions from Java EE to Jakarta EE. Custom extensions depending on classes javax.* must be updated and depends on the same classes but from package jakarta.*.

This has no effect on the custom extension implementation but they must be re-packaged and updated on the deployment.

Note that some dependencies have been removed from Keycloak release (openshift-rest-client, okio-jvm, okhttp, commons-lang, commons-compress, jboss-dmr and kotlin-stdlib). If your extension relies on one or more of these libraries in a transitive manner, you'll have to add them explicitly in your package framework.

Because of the new feature user session note mapper, note that mappers that uses a claim with a dot in the name must be adapted to escape the dot that has become a special character.

Adapt mapper
Adapt mapper

From this version, the custom extensions must be compiled against Java 17.

Migrating to 23.x ​

This version of Keycloak essentially improves existing features.

However, Keycloak has switched to RESTEasy Reactive. SPIs that rely on JAX-RS API should be compatible with this change. SPI’s that depend on RESTEasy Classic including ResteasyClientBuilder will not be compatible and will require update, this will also be true for other implementation of the JAX-RS API like Jersey.

The other main concern of this version is a review of the themes that might need some migration. Checkout the official guide

Migrating to 24.x ​

In this version of Keycloak user profile feature is now supported and enabled by default. In the previous version this feature was a preview feature.

This feature can lead to some breaking changes. Here is the documentation related to these changes. You will now have access to a new welcome page which will provide a link to the documentation, community and some blogs.

The v3 account console is now the default one after being added as a preview feature in the v22 official guide.

The v24 introduces a novel password hashing technique that will be used for the new users. While v23 employed 27,500 iterations using the sha256 algorithm, this upgraded version now employs 210,000 iterations with the sha512 algorithm. Consequently, this results in significantly longer response times (roughly three times longer than v23) and considerably higher CPU usage for every issued token. This issue is already noticed by Keycloak and should be improved in the v25 as explained here.


This new settings do not impact the performance of existing users, however, if you plan to add a lot of new users, you should set a password policy to override the default values coming with version 24.

For each realm, in the Authentication > Policies > Password policy, create two entries:

  • Hashing Algorithm: pbkdf2-sha256
  • Hashing Iterations: 27500
Password policy override
Password policy override

Afterward, when the v25 will come with the new algorithm, you will simply have to remove these settings.

Migration to the new version will entail approximately a two-minute downtime. If this downtime poses any challenges for your deployment, kindly inform us of your preferred scheduling time.

Migrating to 25.x ​

In this new major version of Keycloak, new preview features are available:

  • organization: provides a realm with some core CIAM capabilities, which will serve as the baseline for more capabilities in the future to address Business-to-Business (B2B) and Business-to-Business-to-Customers (B2B2C) use cases
  • passkeys: there is a dedicated authenticator available, which means you can select from a list of available passkeys accounts and authenticate a user based on that

In the previous major version v24.x, hash iterations using a new PBKDF2 algorithm were increased from 27.5K to 210K, resulting in a more than 10-fold increase in the CPU time required to generate a password hash. With Argon2, better security can be achieved with almost the same CPU time as previous versions of Keycloak. The user credentials will be automatically migrated to these latest algorithm settings.

v24.x deployment

If you are running v24.x deployment and have configured a password policy to keep pbkdf2-sha256 algorithm and 27500 hashing iterations as suggested above, you need to delete those settings to take advantage of the latest algorithm settings.

From this version, the custom extensions must be compiled against OpenJDK 21.


Migration to this new version will result in a two-minute downtime and loss of sessions. If this downtime causes problems for your deployment, please let us know when you would prefer to migrate.

If you are using an older version of keycloak-js adapter, you will have issue to login resulting an "Invalid nonce, clearing token" errors. In order to mitigate this, you can either :

  • upgrade your keycloak-js library to the latest version
  • add the predefined "Nonce backwards compatible" mapper through the "By Configuration" button into the dedicated scope of your client
Configure Nonce Mapper for backward compatibility
Configure Nonce Mapper for backward compatibility

More information about it from the official upgrade guide