Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: Proxy, TLS, zwei Instanzen, Export, Upgrade

Ziel: Keycloak hinter einen TLS-Proxy stellen, als Cluster aus zwei Instanzen betreiben, alle Adressen umziehen, Gesundheit und Metriken abfragen, einen Realm exportieren, ein Upgrade auf einer Probe-Instanz testen und Passkeys einschalten. · Dauer: ca. 150 min · Voraussetzung: Tag 11

Briefing

  • In Produktion endet TLS meist an einem Reverse Proxy. Keycloak spricht dahinter HTTP und erfährt aus den X-Forwarded-*-Headern, wie der Browser es erreicht hat (KC_PROXY_HEADERS=xforwarded).
  • Mehrere Instanzen mit derselben Datenbank bilden einen Cluster. Sie finden sich über die Datenbank (JDBC_PING) und teilen Caches per Infinispan. Sitzungen liegen zusätzlich in der Datenbank – ein Ausfall einer Instanz meldet niemanden ab.
  • Der Hostname ist Teil jedes Tokens (iss). Ändert er sich, müssen alle mit: Anwendungen, Broker, SAML-Partner.
  • Health und Metriken liefert Keycloak auf dem Management-Port 9000.
  • Export schreibt einen Realm samt Benutzern als JSON. Upgrades testet man auf einer Kopie, bevor man sie in Produktion fährt.
  • Passkeys (WebAuthn) verlangen einen sicheren Kontext: HTTPS mit einem Zertifikat, dem der Browser vertraut.
 Browser/notes ─https─► Caddy :443 (Zertifikat der Lab-CA)
                          ├─► keycloak   :8080 ─┐
                          └─► keycloak-2 :8080 ─┴─► kc-db (Postgres, JDBC_PING)

Drill 1: Eine eigene CA

Für sslip.io-Namen im eigenen Netz stellt keine öffentliche CA ein Zertifikat aus. Wir bauen eine Lab-CA und signieren damit das Zertifikat für kc.<IP>.sslip.io:

source ~/kc-lab/setup/env.sh
mkdir -p ~/kc-lab/tag12 ~/kc-lab/tls && cd ~/kc-lab/tls
openssl req -x509 -newkey rsa:3072 -nodes -days 3650 -subj "/CN=notes Lab CA" \
  -keyout ca.key -out ca.pem 2>/dev/null
openssl req -newkey rsa:2048 -nodes -subj "/CN=kc.$VM_IP.sslip.io" \
  -keyout kc.key -out kc.csr 2>/dev/null
printf 'subjectAltName=DNS:kc.%s.sslip.io\nextendedKeyUsage=serverAuth\n' "$VM_IP" \
  > kc.ext
openssl x509 -req -in kc.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 397 \
  -extfile kc.ext -out kc.pem
chmod 644 kc.key
openssl x509 -in kc.pem -noout -issuer -ext subjectAltName

Erwartet:

Certificate request self-signature ok
subject=CN = kc.192.168.64.5.sslip.io
issuer=CN = notes Lab CA
X509v3 Subject Alternative Name: 
    DNS:kc.192.168.64.5.sslip.io

Browser prüfen nur noch den Subject Alternative Name, nicht den CN. Damit curl, Terraform (Tag 13) und alle anderen Werkzeuge der VM der Lab-CA vertrauen, kommt sie in den Zertifikatsspeicher des Systems:

sudo cp ~/kc-lab/tls/ca.pem /usr/local/share/ca-certificates/notes-lab-ca.crt
sudo update-ca-certificates 2>&1 | tail -1

Erwartet:

done.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Zwei Instanzen hinter Caddy

Der Begleitcode hat eine neue Compose-Datei für das Projekt keycloak: dieselbe Datenbank, zwei Keycloak-Instanzen und Caddy als Proxy.

cd ~/kc-lab/keycloak
grep -E 'KC_PROXY|keycloak-2:|image: caddy|443' ~/kc-lab/code/keycloak-ha/compose.yaml
cat ~/kc-lab/code/keycloak-ha/Caddyfile

Erwartet:

    KC_PROXY_HEADERS: xforwarded        # Proxy setzt X-Forwarded-*
  keycloak-2:
    image: caddy:2.11.7-alpine
      - "443:443"
# Caddyfile – TLS mit dem Zertifikat der Lab-CA, Lastverteilung auf zwei Instanzen
kc.{$VM_IP}.sslip.io {
    tls /certs/kc.pem /certs/kc.key
    reverse_proxy keycloak:8080 keycloak-2:8080 {
        lb_policy round_robin
        health_uri /health/ready
        health_port 9000
        health_interval 5s
    }
}

Caddy fragt jede Instanz alle fünf Sekunden nach /health/ready und schickt Anfragen nur an gesunde. Port 8080 ist nicht mehr nach außen offen – alles geht über 443. Ab jetzt heißt Keycloak https://kc.<IP>.sslip.io. Das merken wir uns in vms.env, das env.sh am Ende einliest:

echo 'export KC_URL="https://kc.$VM_IP.sslip.io"' >> ~/kc-lab/setup/vms.env
source ~/kc-lab/setup/env.sh && echo "$KC_URL"
cp ~/kc-lab/tls/ca.pem ~/kc-lab/keycloak/truststores/lab-ca.pem
cp compose.yaml compose.tag01.yaml
cp ~/kc-lab/code/keycloak-ha/compose.yaml ~/kc-lab/code/keycloak-ha/Caddyfile .
docker compose up -d --wait 2>&1 | grep -E 'Healthy|Started'
docker compose ps --format '{{.Service}}\t{{.Status}}'
kclogin
curl -s $KC_URL/realms/lab/.well-known/openid-configuration | jq -r .issuer

Erwartet (gekürzt, nach ein bis zwei Minuten):

https://kc.192.168.64.5.sslip.io
 Container keycloak-keycloak-1 Started
 Container keycloak-keycloak-2-1 Started
 Container keycloak-proxy-1 Started
…
 Container keycloak-keycloak-2-1 Healthy
 Container keycloak-keycloak-1 Healthy
kc-db   Up 3 hours (healthy)
keycloak    Up 1 minute (healthy)
keycloak-2  Up 1 minute (healthy)
proxy   Up 1 minute
Logging into http://localhost:8080 as user kcadmin of realm master
https://kc.192.168.64.5.sslip.io/realms/lab
  • Die Lab-CA liegt auch im Truststore von Keycloak. Keycloak ruft sich als Broker selbst über $KC_URL auf (Drill 4) und muss dem Zertifikat dann trauen.
  • kclogin ist nötig, weil die neuen Container die alte Anmeldung von kcadm nicht kennen. kcadm spricht weiter intern mit http://localhost:8080.
  • Der issuer ist jetzt die https-Adresse – ohne Port.

Haben die beiden Instanzen sich gefunden?

docker compose logs keycloak-2 | grep -o 'ISPN000094: Received new cluster view.*' \
  | tail -1 | cut -c1-60
curl -s 127.0.0.1:9000/metrics | grep '^vendor_cluster_size'

Erwartet:

ISPN000094: Received new cluster view for channel ISPN: [
vendor_cluster_size{cache_manager="keycloak",node="…"} 2.0

Fortschritt speichern? Kostenlos registrieren

Drill 3: notes zieht mit

oauth2-proxy und notes-api holen Discovery und JWKS jetzt per https. Beide sind in Go geschrieben und lesen vertrauenswürdige CAs aus der Datei in SSL_CERT_FILE. Docker Compose liest eine compose.override.yaml im Projektordner automatisch mit:

cd ~/kc-lab/notes
cat ~/kc-lab/code/notes-stack/compose.tls.yaml | grep -v '^#' | head -6
cp ~/kc-lab/code/notes-stack/compose.tls.yaml compose.override.yaml
docker compose up -d --wait 2>&1 | grep -c Healthy
jwt "$(token)" | jq -r .iss

Erwartet:

services:
  migrate:
    environment:
      SSL_CERT_FILE: /etc/lab-ca.pem
    volumes:
      - ../tls/ca.pem:/etc/lab-ca.pem:ro
5
https://kc.192.168.64.5.sslip.io/realms/lab

docker compose up erzeugt alle Container neu, deren Konfiguration sich geändert hat – hier wegen der neuen KC_URL und der Override-Datei. Öffne notes im Browser und melde dich als anna an. Der Browser warnt vor dem Zertifikat von Keycloak, weil er die Lab-CA nicht kennt; für den Moment kannst du die Warnung wegklicken (Drill 8 macht es richtig). notes selbst läuft weiter über HTTP auf Port 4180.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Alle Adressen umziehen

Broker und SAML aus Tag 11 kennen noch die alte Adresse. Wo genau? Ein Partial Export liefert die Konfiguration eines Realms ohne Benutzer:

OLD="http://kc.$VM_IP.sslip.io:8080"
alt() { kcadm create "realms/$1/partial-export?exportClients=true" -o 2>/dev/null \
  | jq -r --arg o "$OLD" '(.clients[]? | select(tostring | contains($o))
      | "client \(.id) \(.clientId)"), (.identityProviders[]?
      | select(tostring | contains($o)) | "idp \(.alias)")'; }
alt lab; alt partner

Erwartet:

client … http://kc.192.168.64.5.sslip.io:8080/realms/partner
idp partner
client … lab-broker
idp notes-lab

Vier Objekte. Wir holen jedes, ersetzen die Adresse und schreiben es zurück:

umziehen() { kcadm get "$2" -r "$1" | sed "s#$OLD#$KC_URL#g" \
  | kcadm update "$2" -r "$1" -f - && echo "$1 $2 umgezogen"; }
SID=$(kcadm get clients -r lab -q clientId=$OLD/realms/partner | jq -r '.[0].id')
LB=$(kcadm get clients -r partner -q clientId=lab-broker | jq -r '.[0].id')
umziehen lab clients/$SID
umziehen partner clients/$LB
umziehen partner identity-provider/instances/notes-lab
umziehen lab identity-provider/instances/partner

Erwartet:

lab clients/… umgezogen
partner clients/… umgezogen
partner identity-provider/instances/notes-lab umgezogen
Client secret must be re-entered when the token URL, client ID, authentication method, …

Keycloak gibt Secrets nie heraus – kcadm get liefert **********. Ändert sich die Token-URL, verlangt Keycloak das Secret erneut, damit es nicht an eine fremde Adresse geht. Also setzen wir es beim Zurückschreiben:

kcadm get identity-provider/instances/partner -r lab | sed "s#$OLD#$KC_URL#g" \
  | jq '.config.clientSecret = "lab-client-secret-123"' \
  | kcadm update identity-provider/instances/partner -r lab -f - && echo umgezogen
alt lab; alt partner; echo "Rest: keiner"

Erwartet:

umgezogen
Rest: keiner

Melde dich in einem privaten Fenster über Sign in with Partner GmbH als pia bei notes an und über die Account-Konsole von partner per SAML als anna – beides geht wieder.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Eine Instanz fällt aus

cd ~/kc-lab/keycloak
OIDC=$KC_URL/realms/lab/protocol/openid-connect
R=$(curl -s -d grant_type=password -d client_id=notes-cli \
  -d client_secret=lab-client-secret-123 -d username=anna -d password=lab-user-pw-123 \
  -d scope=openid $OIDC/token | jq -r .refresh_token)
docker compose stop keycloak 2>&1 | tail -1
for i in 1 2 3 4; do
  curl -s -o /dev/null -w '%{http_code} ' $KC_URL/realms/lab
done; echo
curl -s -d grant_type=refresh_token -d client_id=notes-cli \
  -d client_secret=lab-client-secret-123 -d refresh_token=$R $OIDC/token \
  | jq -c '{ok: (.access_token != null)}'
docker compose start keycloak 2>&1 | tail -1
until docker compose ps keycloak | grep -q healthy; do sleep 5; done; echo wieder da
kclogin

Erwartet:

 Container keycloak-keycloak-1 Stopped
200 200 200 200
{"ok":true}
 Container keycloak-keycloak-1 Started
wieder da
Logging into http://localhost:8080 as user kcadmin of realm master

Caddy merkt den Ausfall am Health-Check und schickt alles an keycloak-2. Annas Sitzung lebt weiter: Der Refresh Token funktioniert, obwohl die Instanz weg ist, bei der sie sich angemeldet hat.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Gesundheit und Metriken

curl -s 127.0.0.1:9000/health/ready | jq -c '{status, checks: (.checks | length)}'
curl -s 127.0.0.1:9000/health/ready | jq -r '.checks[].name' | sort
curl -s 127.0.0.1:9000/metrics | grep -E '^vendor_cluster_size|^agroal_active_count'

Erwartet:

{"status":"UP","checks":4}
Graceful Shutdown
Keycloak Initialized
Keycloak cluster health check
Keycloak database connections async health check
vendor_cluster_size{cache_manager="keycloak",node="…"} 2.0
agroal_active_count{datasource="default"} 0.0
  • /health/ready prüft Datenbank und Cluster – das ist die richtige Frage für einen Load Balancer. /health/live sagt nur, ob der Prozess lebt.
  • /metrics liefert das Prometheus-Format: agroal_* ist der Verbindungspool zur Datenbank, vendor_* sind Cache und Cluster, http_server_* die Anfragen.
  • Port 9000 ist bewusst nur lokal erreichbar. Über den Proxy gibt es ihn nicht.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Export und Upgrade-Probe

Ein Export läuft als eigener Keycloak-Prozess gegen dieselbe Datenbank:

mkdir -p ~/kc-lab/tag12/export && cd ~/kc-lab/keycloak
docker compose run --rm --no-deps -v ~/kc-lab/tag12/export:/export keycloak \
  export --dir /export --realm lab --users realm_file 2>&1 | grep -o 'KC-SERVICES0035.*'
jq -c '{realm, users: (.users | length), clients: (.clients | length),
  idps: (.identityProviders | length)}' ~/kc-lab/tag12/export/lab-realm.json

Erwartet:

KC-SERVICES0035: Export finished successfully
{"realm":"lab","users":11,"clients":10,"idps":1}

Die Datei enthält alles: Rollen, Flows, Clients mit Secrets, Benutzer mit Passwort-Hashes. Behandle sie wie ein Backup der Datenbank. Mit ihr testen wir ein Upgrade: Eine Probe-Instanz mit eigener Datenbank startet mit Keycloak 26.8.0 und importiert den Realm.

cp -R ~/kc-lab/code/kc-probe ~/kc-lab/kc-probe && cd ~/kc-lab/kc-probe
mkdir -p import && cp ~/kc-lab/tag12/export/lab-realm.json import/
grep -E 'image: quay|command' compose.yaml
docker compose up -d --wait 2>&1 | tail -1
docker compose logs probe | grep -o -E "Realm 'lab' imported|Keycloak 26[.0-9]* on JVM"

Erwartet:

    image: quay.io/keycloak/keycloak:${KC_VERSION:-26.8.0}
    command: ["start-dev", "--import-realm"]
 Container kc-probe-probe-1 Healthy
Realm 'lab' imported
Keycloak 26.8.0 on JVM

Seit Keycloak 26 sagt update-compatibility, ob ein Upgrade rolling gehen kann – Instanz für Instanz ohne Ausfall – oder ob alle Instanzen gleichzeitig neu starten müssen. Die alte Version schreibt ihre Metadaten, die neue prüft sie:

docker compose exec -T probe /opt/keycloak/bin/kc.sh update-compatibility metadata \
  --file=/tmp/meta.json >/dev/null
docker compose cp probe:/tmp/meta.json ./meta-26.8.0.json 2>/dev/null
KC_VERSION=26.8.1 docker compose run --rm --no-deps \
  -v ./meta-26.8.0.json:/tmp/m.json:ro probe update-compatibility check \
  --file=/tmp/m.json 2>&1 | grep -E '^\['
KC_VERSION=26.8.1 docker compose up -d --wait 2>&1 | tail -1
docker compose logs probe --since 3m | grep -o -E "Keycloak 26[.0-9]* on JVM"
curl -s localhost:8081/realms/lab | jq -r .realm

Erwartet:

[cacheEmbedded] Provider is compatible.
[cacheRemote] Provider is compatible.
[database] Provider is compatible.
[feature-compatibility] Provider is compatible.
[jgroupsMtls] Provider is compatible.
[keycloak] Provider is compatible.
[OK] Rolling Update is available.
 Container kc-probe-probe-1 Healthy
Keycloak 26.8.1 on JVM
lab

Die Probe läuft mit 26.8.1 auf der Datenbank von 26.8.0 – das Upgrade ist getestet. In Produktion tauschst du jetzt das Image einer Instanz nach der anderen.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Passkeys

Jetzt gibt der Browser WebAuthn frei – wenn er dem Zertifikat traut. Kopier die Lab-CA auf deinen Rechner und vertrau ihr dort. Auf dem Mac (nicht auf der VM):

multipass transfer kc:kc-lab/tls/ca.pem ./notes-lab-ca.pem
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain notes-lab-ca.pem

Unter Windows importierst du die Datei mit einem Doppelklick in Vertrauenswürdige Stammzertifizierungsstellen, unter Linux wie in Drill 1. Firefox hat einen eigenen Speicher (Einstellungen → Zertifikate → Importieren). Danach den Browser neu starten. Nun Passkeys einschalten und anna zur Registrierung auffordern:

kcadm update realms/lab -s webAuthnPolicyPasswordlessPasskeysEnabled=true
AID=$(kcadm get users -r lab -q username=anna -q exact=true | jq -r '.[0].id')
kcadm update users/$AID -r lab -s 'requiredActions=["webauthn-register-passwordless"]'
echo "$KC_URL/realms/lab/account"

Erwartet:

https://kc.192.168.64.5.sslip.io/realms/lab/account

Melde dich dort als anna mit Passwort an. Keycloak verlangt die Registrierung eines Passkeys:

anna registriert einen Passkey

Klick auf Register, bestätige mit Fingerabdruck, PIN oder Handy und gib als Namen laptop ein. Danach:

kcadm get users/$AID/credentials -r lab \
  | jq -r '.[] | [.type, .userLabel // "-"] | @tsv'

Erwartet:

password    -
webauthn-passwordless   laptop

Melde dich ab. Die Login-Seite bietet jetzt Sign in with Passkey an – ein Klick, ohne Benutzername und Passwort. Browser mit Passkey-Unterstützung schlagen ihn auch direkt im Feld Username vor.

Login mit Passkey

Annas Passwort gilt weiter, der Password Grant (token) funktioniert also wie bisher.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cd ~/kc-lab/keycloak
docker compose ps --format '{{.Service}}' | sort | tr '\n' ' '; echo

Erwartet: Datenbank, zwei Instanzen, Proxy.

kc-db keycloak keycloak-2 proxy 
curl -s -o /dev/null -w '%{http_code} %{ssl_verify_result}\n' $KC_URL/realms/lab

Erwartet: Antwort über TLS, Zertifikat geprüft (0 = in Ordnung).

200 0
jwt "$(token)" | jq -r .iss

Erwartet:

https://kc.192.168.64.5.sslip.io/realms/lab
curl -s 127.0.0.1:9000/metrics | grep '^vendor_cluster_size' | grep -o '[0-9.]*$'

Erwartet:

2.0

Challenge

Die Probe-Instanz enthält eine Kopie von lab. Zeig, dass sich anna dort mit ihrem Passwort ein Token holen kann, und räum die Probe danach samt Datenbank ab.

Hinweis: Die Probe hört auf localhost:8081. Export und Import nehmen Client-Secrets und Passwort-Hashes mit.

Lösung

curl -s -d grant_type=password -d client_id=notes-cli \
  -d client_secret=lab-client-secret-123 -d username=anna -d password=lab-user-pw-123 \
  localhost:8081/realms/lab/protocol/openid-connect/token \
  | jq -c '{ok: (.access_token != null)}'
cd ~/kc-lab/kc-probe && docker compose down -v 2>&1 | grep -c Removed

Erwartet:

{"ok":true}
4

down -v entfernt auch das Volume probe-data. Der Export unter ~/kc-lab/tag12 bleibt – Tag 15 braucht ihn.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Echte Zertifikate: Mit öffentlichem Namen per ACME (Let’s Encrypt), im Unternehmen von der internen CA. Kürzere Laufzeiten heißen: Erneuerung automatisieren.
  • TLS bis Keycloak: Wer auch intern verschlüsseln muss, gibt Keycloak ein eigenes Zertifikat (KC_HTTPS_CERTIFICATE_FILE) und lässt den Proxy per reencrypt sprechen.
  • Admin-Konsole nicht öffentlich: Mit KC_HOSTNAME_ADMIN bekommt die Konsole einen eigenen, nur intern erreichbaren Namen; der Proxy leitet /admin nach außen nicht weiter.
  • Cluster in Kubernetes: Der Operator (Tag 14) setzt Discovery, Health-Checks und Rolling Updates selbst um. Mehrere Rechenzentren brauchen ein externes Infinispan.
  • Backups: Der Export ist kein Ersatz für Datenbank-Backups (pg_dump, PITR). Er eignet sich, um Realms zwischen Umgebungen zu kopieren.