How are Keycloak version upgrade handled at Cloud-IAM
One of the key of security, is to keep the software up-to-date to avoid exploit of known issues.
The team is responsible of 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.
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 diagnose in case an upgrade introduced an issue with your deployment, the deployment can only be upgraded one major version at a time.
For freemium, the instance is shared across multiple deployments.
The servers are upgraded without notice.
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.
To let the customers plan the upgrade and some internal qualification or development, the Cloud team publishes a schedule of the next versions deprecation.
Customer are welcomed to ask the Cloud-IAM support team to upgrade to the latest versions without waiting for the deprecation deadline
This version is mostly related to Wildfly upgrade.
Nothing is related to the change of SPI in this version.
This version is mostly related to the introduction of Quarkus.
Nothing is related to the change of SPI in this version.
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: https://www.keycloak.org/docs/latest/server_development/#_script_providers
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.
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
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/{{realm}}/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.
Check if the applications are using this endpoint and ensure the scope of the tokens are properly configured.
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.
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.
The team is responsible of 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 diagnose 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.
Upgrade plan
To let the customers plan the upgrade and some internal qualification or development, the Cloud team publishes a schedule of the next versions deprecation.
| Version | Release date | Deprecation at Cloud-IAM | Release note |
|---|---|---|---|
| Keycloak 15.x Wildfly | August 2021 | end of January 2023 | link |
| Keycloak 16.x Wildfly | December 2021 | end of February 2023 | link |
| Keycloak 17.x Wildfly | February 2022 | end of February 2023 | link |
| Keycloak 18.x Wildfly | April 2022 | end of March 2023 | link |
| Keycloak 18.x Quarkus | April 2022 | end of June 2023 | link |
| Keycloak 19.x Quarkus | August 2022 | end of September 2023 | link |
| Keycloak 20.x | November 2022 | end of November 2023 | link |
| Keycloak 21.x | April 2023 | end of April 2024 | link |
Customer are welcomed to ask the Cloud-IAM support team to upgrade to the latest versions without waiting for the deprecation deadline
Migration warnings
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: https://www.keycloak.org/docs/latest/server_development/#_script_providers
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/{{realm}}/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"
...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.
Updated on: 25/05/2023
Thank you!