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

Introduction

This document lists the steps to migrate from old Keycloak versions to each Keycloak version described.

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

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

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

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


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

# DB
db=postgres
YML

 Upgrade from Keycloak 20 to 21

Use the following commands to upgrade.

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
BASH

Upgrade from an older Keycloak to Keycloak 21

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

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 20) will coexist at same time.
  • Stop the old Keycloak instance
    $ systemctl stop keycloak
    BASH
  • Do a backup from Database.

Steps

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

    [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
    TEXT
  • Install the new keycloak package
    yum install keycloak-20 --enablerepo="censhare*"
    BASH
  • 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:
      # 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>
...
      BASH
    • Regarding TLS/SSL, keycloak already have an internal certificate file, so a new one will not be required
  • Start the new Keycloak instance
    $ systemctl stop key cloak-20
    BASH
  • 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:
    $ yum remove keycloak
    BASH

Keycloak - manual changes

1) TLS/SSL keystore

In Keycloak 9, we declare our SSL keystore under security-realm as follows:

<security-realm name="ApplicationRealm">
                <server-identities>
                    <ssl>
                        <keystore path="cs-test20212-css01.jks" relative-to="jboss.server.config.dir" keystore-password="corpus" alias="cs-test20212-css01.censhare.com"/>
                    </ssl>
				</server-identities>
XML

In Keycloak 16, to declare the SSL keystore, you use a proper entry. Add the SSL keystore options in /opt/jboss/keycloak/standalone/configuration/standalone.xml as follows:

<tls>
	<key-stores>
	...
		<key-store name="censhareKS">
        	<credential-reference clear-text="corpus"/>
            <implementation type="JKS"/>
            <file path="keystore-name.jks" relative-to="jboss.server.config.dir"/>
        </key-store>
	...
    </key-stores>
	<key-managers>
	...
		<key-manager name="censhareKM" key-store="censhareKS">
        	<credential-reference clear-text="corpus"/>
    	</key-manager>
	...
	</key-managers>
	<server-ssl-contexts>
	...
		<server-ssl-context name="censhareSSC" key-manager="censhareKM"/>
	...
	</server-ssl-contexts>
</tls>
...
<server name="default-server">
	...
    <https-listener name="https" proxy-address-forwarding="true" socket-binding="https" ssl-context="censhareSSC" enable-http2="true"/>
	...
</server>
XML

Place the keystore file in /opt/jboss/keycloak/standalone/configuration.

2) PostgreSQL Database connection

To use your PostgreSQL again, go to /opt/jboss/keycloak/standalone/configuration/standalone.xml, remove the KeycloakDS entry from datasources, then add the following:

<subsystem xmlns="urn:jboss:domain:datasources:6.0">
     <datasources>
       ...
       <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
           <connection-url>jdbc:postgresql://localhost/keycloak</connection-url>
           <driver>postgresql</driver>
           <pool>
               <max-pool-size>20</max-pool-size>
           </pool>
           <security>
               <user-name>William</user-name>
               <password>password</password>
           </security>
       </datasource>
        ...
     </datasources>
  </subsystem>
XML

H2 Database changes

  • Recreate your system admin user

As described here.

  • Import censhare realm 

In the Keycloak Admin Console, import your censhare realm. This can be done upon creation of a new realm. Remember to disable/delete the encryption algorithms (called Key Providers) in the realm settings.

  1. Open the Keycloak admin console at http://localhost:8080/auth/ and log in with the admin user credentials that you set in the previous step.
  2. In the left sidebar, click the Master realm and select Create realm.
  3. Drag-and-drop or browse the exported file from the previous step.
  4. Enable your realm
  5. Click Create.
  6. In your new realm, go to the left navigation panel.
  7. Under Configure, in the Realm settings, go to the Keys tab, and on this tab, to the Providers tab.
  8. Check if the following providers are in the list:
    • rsa-enc-generated
    • fallback-ES256
  9. If they are listed, disable or delete them if only disabling them is not possible.
  • 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.
  • Also, change the client secrets in the Cloud Gateway in /opt/censer/cloud-gateway/application.yml:
## Please use client secret from your keycloak server here:
spring.security.oauth2.client.registration.keycloak.client-secret: your_censhare5_client_secret
XML
  • Restart Keycloak:
$ systemctl start keycloak
BASH
  • Recreate user for censhare-server

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 Keycloak, go to the censhare realm and add this user here. Follow these instructions.

  • 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.