Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Upgrading Guide

Red Hat build of Keycloak 22.0

Red Hat Customer Content Services

Abstract

This book is a guide to upgrading your application from a previous version of Red Hat build of Keycloak 22.0.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Upgrading Red Hat build of Keycloak

Red Hat build of Keycloak is based on the Keycloak project, which enables you to secure your web applications by providing Web SSO capabilities based on popular standards such as OpenID Connect, OAuth 2.0, and SAML 2.0. The Red Hat build of Keycloak server acts as an OpenID Connect or SAML-based identity provider (IdP), allowing your enterprise user directory or third-party IdP to secure your applications by using standards-based security tokens.

This guide applies to version 22.0.13, which is a minor version of Red Hat build of Keycloak. To upgrade Red Hat build of Keycloak to version 22.0.13, use the following procedures in this order:

  1. Upgrade the Red Hat build of Keycloak server
  2. Upgrade Red Hat build of Keycloak adapters

Chapter 2. Upgrading the Red Hat build of Keycloak server

2.1. Preparing for upgrading

Procedure

  1. Back up the old installation, such as configuration, themes, and so on.

  2. Back up the database using instructions in the documentation for your relational database.

    The database will no longer be compatible with the old server after the upgrade. If you need to revert the upgrade, first restore the old installation, and then restore the database from the backup copy.

  3. Handle any open transactions and delete the data/tx-object-store/ transaction directory.
Note

In a minor upgrade of Red Hat build of Keycloak, all user sessions are lost. After the upgrade, all users will have to log in again.

2.2. Downloading the server ZIP file

Procedure

  1. Download Red Hat build of Keycloak from the Red Hat website and extract it.
  2. Move the ZIP file to the desired location.

  3. Extract the archive.

    After extracting this file, you should have a directory that is named rhbk-22.0.13.

  4. Copy conf/, providers/ and themes/ from the previous installation to the new installation.

2.3. Database migration

Red Hat build of Keycloak can automatically migrate the database schema, or you can choose to do it manually. By default, the database is automatically migrated when you start the new installation for the first time.

2.3.1. Automatic relational database migration

To perform an automatic migration, start the server connected to the desired database. If the database schema has changed for the new version of the server, it will be migrated.

Creating an index on huge tables with millions of records can be very time-consuming and possibly cause a major service disruption. Therefore, a threshold exists to limit the number of records allowed for the index. A warning message appears in the server logs with SQL commands you can apply later manually.

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

kc.[sh|bat] start --spi-connections-liquibase-default-index-creation-threshold=300000
Copy to Clipboard

2.3.2. Manual relational database migration

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

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-strategy=manual
Copy to Clipboard

When you start the server with this configuration, the server checks if the database needs to be migrated. The required changes are written to the bin/keycloak-database-update.sql SQL file that you can review and manually run against the database.

If you want to change the path and name of the exported SQL file, set the migration-export property for the default connections-jpa provider: 

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-export=<path>/<file.sql>
Copy to Clipboard

For more details on applying this file to the database, see the documentation for your relational database. After the changes have been written to the file, the server exits.

Chapter 3. Upgrading Red Hat build of Keycloak adapters

It is important that you upgrade Red Hat build of Keycloak server first, and then upgrade the adapters. Earlier versions of the adapter might work with later versions of Red Hat build of Keycloak server, but earlier versions of Red Hat build of Keycloak server might not work with later versions of the adapter.

3.1. Compatibility with older adapters

As mentioned above, we try to support newer release versions of Red Hat build of Keycloak server working with older release versions of the adapters. However, in some cases we need to include fixes on the Red Hat build of Keycloak server side which may break compatibility with older versions of the adapters. For example, when we implement new aspects of the OpenID Connect specification, which older client adapter versions were not aware of.

In those cases, we added Compatibility modes. For OpenId Connect clients, there is a section named OpenID Connect Compatibility Modes in the Red Hat build of Keycloak admin console, on the page with client details. Here, you can disable some new aspects of the Red Hat build of Keycloak server to preserve compatibility with older client adapters. More details are available in the tool tips of individual switches.

3.2. Upgrading the EAP adapter

To upgrade an EAP adapter that has been copied to your web application, perform the following procedure.

Procedure

  1. Download the new adapter archive.
  2. Remove the previous adapter modules by deleting the EAP_HOME/modules/system/add-ons/keycloak/ directory.
  3. Unzip the downloaded archive into EAP_HOME.

3.3. Upgrading the JavaScript adapter

To upgrade a JavaScript adapter that has been copied to your web application, perform the following procedure.

Procedure

  1. Download the new adapter archive.
  2. Overwrite the keycloak.js file in your application with the keycloak.js file from the downloaded archive.

3.4. Upgrading the Node.js adapter

To upgrade a Node.js adapter that has been copied to your web application, perform the following procedure.

Procedure

  1. Download the new adapter archive.
  2. Remove the existing Node.js adapter directory
  3. Unzip the updated file into its place
  4. Change the dependency for keycloak-connect in the package.json of your application

Legal Notice

Copyright © 2024 Red Hat, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat