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 made available to our customer.

If you prefer our support team to handle the upgrade process or assist you at any step, please don't hesitate to contact us: we're always here to help!

How are planned the upgrades ​

Little Lemur plans (Free) ​

For freemium, the instance is shared across multiple deployments. The servers are upgraded without notice by Cloud-IAM team.

Dedicated plans ​

For paying plans, the customer has the control of when the deployment will be updated.

The Cloud-IAM Console offers a panel to schedule and target the Keycloak upgrades:

1. Navigate to your Deployment page.
2. Navigate to Pilot tab.
3. Navigate to Upgrade.
4. Select your desired target version.
5. Choose when the upgrade should occur:
   • As Soon As Possible (Immediately)
   • During your next scheduled maintenance window
6. Click on Next steps
7. Read and consent to the upgrade terms (a backup is always performed automatically).
8. Click Apply to initiate the upgrade.

For every upgrade, a cold backup is triggered before the process to make the rollback feasible with a minimal RPO. As all the Cloud-IAM deployments are constantly monitored, if something goes wrong during the upgrade, our on-call team will be trigger and will help you to end / rollback the process.

Be aware that, Keycloak versions are not always backward compatible.

There are multiple use-cases:

• When the cached data are not backward compatible or the library is updated, Cloud-IAM has no other solution than stopping completely the cluster for a very few minutes. The usual downtime is less than 2 minutes between the last node has been stopped, and the first has restarted.
• Changes in Keycloak base theme break the customer theme.
• Changes in the SPI make the custom extension unable to start.

In case additional custom extensions have been uploaded on the deployment, please ensure your extensions are compatible with your chosen target Keycloak version. If compatibility is unclear or adjustments are necessary, contact our support team to help manage your extensions.

::: note Upgrading multiple majors We generally discourage the upgrade of a Keycloak cluster by jumping multiple major releases because it often makes the process of debugging or detecting issues more complex.

However, we do offer the possibility to jump multiple versions. All the database changes and data migrations are applied sequentially. :::

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.

Possible impact of migration ​

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 this version implies a downtime because of cache backward compatibility issue.

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 this version implies a downtime because of cache backward compatibility issue.

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.

Migrating to this version implies a downtime because of cache library update.

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 this version implies a downtime because of cache library update.

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.

TIP

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

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.

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.

From this version, the custom extensions can be compiled with Java 21.

If you are using an older version of keycloak-js adapter, you will have issue to login resulting an "Invalid nonce, clearing token" errors. A symptom could also be an infinite redirection loop after login.

In order to mitigate this, you can either:

• upgrade your keycloak-js library to the latest version (preferred)
• add the predefined "Nonce backwards compatible" mapper through the "By Configuration" button into the dedicated scope of your client

More information about it from the official upgrade guide

Migrating to this version implies a downtime because of cache transport library update.

Migrating to 26.x ​

Here is the official guide of this new version. Some feature previews are now native in this new version.

• 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
• persistent-user-sessions: the sessions are stored in the database. This means that during a migration, from the 25 to 26 migration, you will not lose your sessions anymore.
• new admin console : a new login theme is now introduced with the capability to use a dark mode.

The migration to v26 includes a two minutes downtime, contact our support team if you are interested by this migration.

Check the theme migration official guide to adapt your custom extensions.

Migrating to this version implies a downtime because of cache library update.

Migrating to 26.1 ​

Here is the official guide of this new version. This version helps the Cloud-IAM to have a better monitoring tools and an improved support on your deployment.

Migrating to this version does not imply any downtime.

Migrating to 26.2 ​

Checkout the release note of the version.

It introduces significant enhancements, including support for Standard Token Exchange (RFC 8693), enabling secure token-to-token exchanges. The update also brings Fine-Grained Admin Permissions V2, offering administrators precise control over realm resources through a centralized Permissions section in the Admin Console.

Additionally, SMTP XOAUTH2 support facilitates token-based authentication for outgoing emails with providers like Microsoft and Google.

Migrating to this version does not imply any downtime.