Upgrade Keycloak

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

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.

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.

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
  
  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-20 --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 stop key cloak-20

• 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

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>

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>

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>

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.

• 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

• Restart Keycloak:

$ systemctl start keycloak

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