Wir empfehlen die Verwendung eines aktuellen Keycloaks.

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.

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: docker-nob-erf.next-level-apps.com/keycloak:2022-07-04-02
	#image: quay.io/keycloak/keycloak:20.0.3
    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"