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 subjectAltNameErwartet:
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 -1Erwartet:
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/CaddyfileErwartet:
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 .issuerErwartet (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_URLauf (Drill 4) und muss dem Zertifikat dann trauen. kcloginist nötig, weil die neuen Container die alte Anmeldung vonkcadmnicht kennen.kcadmspricht weiter intern mithttp://localhost:8080.- Der
issuerist 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 .issErwartet:
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 partnerErwartet:
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/partnerErwartet:
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
kcloginErwartet:
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/readyprüft Datenbank und Cluster – das ist die richtige Frage für einen Load Balancer./health/livesagt nur, ob der Prozess lebt./metricsliefert 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.jsonErwartet:
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 .realmErwartet:
[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:
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.
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' ' '; echoErwartet: 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/labErwartet: Antwort über TLS, Zertifikat geprüft (0 = in Ordnung).
200 0
jwt "$(token)" | jq -r .issErwartet:
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 RemovedErwartet:
{"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 perreencryptsprechen. - Admin-Konsole nicht öffentlich: Mit
KC_HOSTNAME_ADMINbekommt die Konsole einen eigenen, nur intern erreichbaren Namen; der Proxy leitet/adminnach 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.