Keycloak aktualisieren

Wir empfehlen die Verwendung eines aktuellen Keycloaks. Unsere UIs wurden zuletzt mit der Version 26.3 erfolgreich gestestet.

Aktualisierung auf 23.0.x oder höher

In Keycloak 23 wurde das Verhalten des Issuer Claims im ID Token und in der Authentifizierungsantwort angepasst. Dadurch schlägt die Authentifizierung in der B2B nach dem Update ohne Konfigurations-Anpassungen fehl.

Um die B2B mit Keycloak 23 oder höher zu verwenden, muss deshalb die Option “Exclude Issuer From Authentication Response” in allen Clients im Keycloak gesetzt werden:

Melden Sie sich dazu zunächst in der Keycloak-Admin-Console an
Selektieren Sie den relevanten Realm, z.B. B2B-QA
Navigieren Sie zu Clients und wählen den gewünschten Client, z.B. b2b-ui
Wechseln Sie in den Reiter Advanced
Scrollen Sie nach unten zum Abschnitt Open ID Connect Compatibility Modes
Setzen Sie die Option Exclude Issuer From Authentication Response auf ON / Aktiviert.
Speichern Sie die Änderungen.

Exclude Issuer From Authentication Response

Aktualisierung von Version 11.0.3 auf 18.0.0 oder 20.0.3

Die früheren Keycloak-Versionen basieren auf JBoss/WildFly. Ab Version 17 setzt Keycloak stattdessen auf Quarkus-basierte Distributionen. Dadurch sind bei einem Update ein paar Dinge in der Konfiguration anzupassen.

Vor einer Aktualisierung empfiehlt sich ein Backup (der Keycloak-Datenbank).

Docker Image

Das Docker Image für Keycloak 18 wird mit dem Tagname docker-nob-erf.next-level-apps.com/keycloak:2022-07-04-02 angeboten.

Grundsätzlich können auch die Keycloak-Docker-Images von quay.io bezogen werden, z.B. für Keycloak 20.0.3 das Image quay.io/keycloak/keycloak:20.0.3

Konfigurations-Anpassungen

Umgebungsvariablen

Viele Umgebungsvariablen wurden in den neueren Keycloak-Versionen umbenannt. Die Namen müssen bei einem Update entsprechend angepasst werden.

Env-Alt	Env-Neu
DB_VENDOR	KC_DB
DB_ADDR	KC_DB_URL_HOST
DB_PORT	KC_DB_URL_PORT
DB_DATABASE	KC_DB_URL_DATABASE
DB_USER	KC_DB_USERNAME
DB_PASSWORD	KC_DB_PASSWORD
KEYCLOAK_USER	KEYCLOAK_ADMIN
KEYCLOAK_PASSWORD	KEYCLOAK_ADMIN_PASSWORD

Start-Befehl

Die Quarkus-basierten Versionen benötigen einen zusätzlichen Start-Befehl. Dieser kann in der docker-compose entweder durch einen zusätzlichen command oder entrypoint angegeben werden.

command: start bzw. command: start-dev

alternativ

entrypoint: "/opt/keycloak/bin/kc.sh start" bzw. entrypoint: "/opt/keycloak/bin/kc.sh start-dev"

Dabei ist start für den Production-Mode und start-dev für den Development-Mode.

Hinweis:
Bei Keycloak 18 kommt es bei verschiedenen Datenbank-Typen wie z.B. Oracle beim Start im Production-Mode zum Fehler Datasource '<default>': No suitable driver found for jdbc:oracle:thin:@//keycloak-database-oracle:1521/orclkc.

Bei Keycloak 20.0.3 konnte dieser Fehler nicht beobachtet werden.

Im Production-Mode kann der Container mit dem Flag “–auto-build“ gestartet werden. Wenn Sie die Option –auto-build verwenden, prüft der Server zunächst, ob sich eine statische Eigenschaft geändert hat (z. B.: Datenbank), und führt automatisch den Build-Befehl aus, bevor der Server tatsächlich gestartet wird.

command:
  - start
  - --auto-build

Hinweis:
Falls ein Mixed-Content aus HTTPS und HTTP verwendet wird, kann dies dazu führen, dass der Keycloak zwar erfolgreich startet aber nicht sein Redirect auf die Admin-Konsole (step1.html wird blockiert). In diesem Fall muss (siehe dazu auch dieser Blog-Eintrag) dem Start-Befehl analog der Command-Flag “–proxy edge“ hinzugefügt werden.

Relativer Pfad /auth

Ab Keycloak-Version 18 wird standard-mäßig nicht mehr der Pfad /auth verwendet.

Da an vielen Stellen auf diesen Pfad zugegriffen wird, ist es möglich dies per Konfiguration wieder als Standard zu definieren. Dafür kann die Umgebungsvariable KC_HTTP_RELATIVE_PATH=/auth gesetzt werden.

Dadurch erspart man sich beispielsweise die Anpassung jeder keycloak.json.

Beispiel docker-compose.yml

docker-compose.yml:

# Keycloak 
version: '3.8'
services:
  keycloak:
	image: quay.io/keycloak/keycloak:22.0.5
    restart: always
    environment:
      - KC_DB=postgres
      - KC_DB_URL_HOST=my.server.de
      - KC_DB_URL_PORT=1234
      - KC_DB_URL_DATABASE=MyDatabase
      - KC_DB_USERNAME=admin
      - KC_DB_PASSWORD=***
      - KC_HTTP_RELATIVE_PATH=/auth
      # these create the first admin account. Remove these properties after first boot.
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=***
	command: start
    #entrypoint: "/opt/keycloak/bin/kc.sh start-dev"

View Me Edit Me

Keycloak Update