Upgrade Keycloak

Learn about the steps to upgrade Keycloak to a later version.

Important notes on Keycloak configuration file

To upgrade Keycloak, you need to download the newer version from https://rpm.censhare.com/tools-release-rpm/. The Keycloak configuration file – /opt/keycloak/conf/keycloak.conf – already has all parameters entered correctly. If you need to add or change anything, you may refer to the official Keycloak documentation: https://www.keycloak.org/server/all-config .

Please do not change the following parameters:

keycloak.conf

YML

# Observability
...
health-enabled=true
metrics-enabled=true

# Log
...
log=file,console
log-file=/var/log/keycloak/server.log

# HTTP
...
http-relative-path=/auth

Use Postgres with Keycloak

We highly recommend using Postgres database with Keycloak. Although Keycloak declares to be compatible with Oracle, unfortunately, we cannot offer support for using Oracle with Keycloak.

In case you use an Oracle database with the censhare Server, you have two options:

utilize it for the Keycloak data: in this case, you have to embrace the risk of using an incompatible database that we cannot support;
set up a separate Postgres database for Keycloak: in this case, remember to specify the following in the keycloak.conf file:

keycloak.conf

YML

# DB
db=postgres

Upgrade from Keycloak 20 to 21

Use the following commands to upgrade.

BASH

systemctl stop keycloak-20
yum remove keycloak-20
yum install keycloak-21 --enablerepo=censhare-tools
cp /opt/keycloak-20.0.3/conf/keycloak.conf.rpmsave /opt/keycloak-21.1.2/conf/keycloak.conf
systemctl start keycloak-21

Upgrade from an older Keycloak to Keycloak 21

If you have one of the older Keycloak versions, please follow those steps.

About H2 database

Using the H2 database in production is strongly discouraged by the developers of Keycloak. This is the reason why we do not use it in our customer installatons.

Prerequisites

From keycloak 17, the wildfly was replaced to quarkus, and with this, it was better to create a new RPM package for it. Both keycloak instances (old and 21) will coexist at same time.
Stop the old Keycloak instance
BASH
```
$ systemctl stop keycloak
```
Do a backup from Database.

Steps

Check if your yum repository for the censhare rpm-tools has the correct values:

TEXT

[censhare-tools]
baseurl = https://user:password@rpm.censhare.com/tools-release-rpm/
enabled = 0
gpgcheck = 1
gpgkey = https://user:password@rpm.censhare.com/public/6CAE093C.pub
name = censhare Repository for 3rd Party Tools

Install the new keycloak package

BASH

yum install keycloak-21 --enablerepo="censhare*"

Edit the entries inside /opt/keycloak/conf/keycloak.conf to adapt to your server (DB user, pass and connection, hostname, etc)
- Since this new version have a lot of changes, the configuration file is very different. To update with all default options, please change only these entries:
  BASH
```
# Basic settings for running in production. Change accordingly before deploying the server.
...
db-url=jdbc:postgresql://<DB_server>/<DB_service>
db-username=<user>
db-password=<password>
...
hostname=<hostname>
...
```
- Regarding TLS/SSL, keycloak already have an internal certificate file, so a new one will not be required
Start the new Keycloak instance
BASH
```
$ systemctl start keycloak-21
```
If the configuration changes work, you will be able to login with current admin user and censhare realm and current users will be available.
After, you can remove the old instance:
BASH
```
$ yum remove keycloak
```

H2 Database migration

Keep our Keycloak configuration tutorial open to understand the instructions below.

In the Keycloak Admin Console:
- Recreate your system admin user.

- Import your censhare realm. This can be done upon creation of a new realm.
- Disable/delete the encryption algorithms (called Key Providers) in the realm settings.

- Change secrets for censhare5 and desktop-app clients
  - For the H2 database, after a new Database instance, the client secrets will be renewed. Therefore, you need to update the secrets in other applications.
  - Go to each of your censhare client pages and select the Credentials tab. Regenerate and copy the respective client secret.
  - Add this secret in the censhare Admin Client under Configuration > Services > Keycloak admin client service:
  - Repeat the step for the desktop-app client.
In the /opt/censer/core-cloud-gateway/application.yml, change the client secrets in the Cloud Gateway:

XML

## Please use client secret from your keycloak server here:
spring.security.oauth2.client.registration.keycloak.client-secret: your_censhare5_client_secret

Restart Keycloak:

BASH

$ systemctl start keycloak

For H2 databases, you must recreate the users that you have, including the user that censhare uses to communicate with Keycloak. To find this user, check the censhare Admin Client, under Configuration > Services > Keycloak admin client service or /opt/corpus/censhare/censhare-Custom/censhare-Server/app/services/keycloak/config.master.xml in the censhare server.
In the Keycloak Admin Console, go to the censhare realm and add this user here.
- Enter the same name that you used before the upgrade and fill in the necessary fields. On the User page, click the Credentials tab and set the same user password that you used before for the upgrade.
- Select the Role Mappings tab. Follow the instructions here to give this user necessary permissions.