Tag 1: Erster Start mit Postgres
Ziel: Keycloak im Produktionsmodus mit Postgres starten, Health und Metriken abfragen, die Admin-Konsole und
kcadm.shkennenlernen, den Realmlabanlegen und den temporären Admin ersetzen. · Dauer: ca. 60 min · Voraussetzung: Tag 0
Briefing
- Ein Realm ist ein abgeschlossener Bereich mit
eigenen Benutzern, Clients und Schlüsseln.
masterverwaltet Keycloak selbst; Anwendungen bekommen eigene Realms. startist der Produktionsmodus: Datenbank, fester Hostname, ohne TLS nur mitKC_HTTP_ENABLED.start-dev(Kong-Buch) ist nur für Experimente.- Der erste Admin ist temporär. Er gehört ersetzt.
kcadm.shist die Kommandozeile für die Admin-API.env.shstellt sie alskcadmbereit.
Browser ──► :8080 Keycloak ──► kc-db (Postgres 18)
du ──► kcadm (im Container) ──► Admin-API
:9000 Health und Metriken (nur 127.0.0.1)
Drill 1: Keycloak starten
source ~/kc-lab/setup/env.sh
mkdir -p ~/kc-lab/tag01
cp -R ~/kc-lab/code/keycloak ~/kc-lab/keycloak && cd ~/kc-lab/keycloak
grep -E 'image:|command:|KC_HOSTNAME|KC_HTTP_ENABLED|KC_BOOTSTRAP' compose.yaml
docker compose up -d --wait
docker compose logs keycloak 2>&1 \
| grep -o 'Keycloak 26.8.1 on JVM.*started in [0-9.]*s'Erwartet (gekürzt, beim ersten Mal bis zu vier Minuten):
image: postgres:18.6-alpine
image: quay.io/keycloak/keycloak:26.8.1
command: ["start"]
KC_HOSTNAME: ${KC_URL:?KC_URL fehlt – source ~/kc-lab/setup/env.sh}
KC_HTTP_ENABLED: "true" # bis Tag 12 ohne TLS
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: lab-admin-pw-123
Container keycloak-keycloak-1 Healthy
Keycloak 26.8.1 on JVM (powered by Quarkus 3.40.1) started in 15.842s
KC_HOSTNAME kommt aus env.sh. Fehlt die
Variable, bricht docker compose mit dem Hinweis aus der
Datei ab, statt Keycloak mit falschem Namen zu starten.
Im Log steht außerdem
WARNING: Likely misconfiguration detected mit dem Hinweis,
dass der Hostname HTTP statt HTTPS benutzt. Ohne TLS ist die Seite für
Browser kein sicherer Kontext; Passkeys (WebAuthn) funktionieren darum
erst mit TLS in Tag 12.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Health und Metriken
curl -s localhost:9000/health/ready | jq -c '{status, checks: [.checks[].name]}'
curl -s localhost:9000/metrics | grep -c '^keycloak_'
curl -s $KC_URL/realms/master | jq -c '{realm, "token-service"}'Erwartet (gekürzt, IP und Zahl weichen bei dir ab):
{"status":"UP","checks":["Graceful Shutdown","Keycloak cluster health check","Keycloak
Initialized","Keycloak database connections async health check"]}
46
{"realm":"master","token-service":"http://kc.192.168.64.7.sslip.io:8080/realms/master/p…
Der Management-Port 9000 liefert Health und Metriken getrennt vom
Port für Benutzer. Direkt nach dem ersten Start antwortet Keycloak eine
Weile mit Bootstrap in progress und
Keycloak Initialized: DOWN, während es die 101 Tabellen in
Postgres anlegt; der Healthcheck der Compose-Datei wartet darauf.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Die Admin-Konsole
Öffne auf dem Laptop
http://kc.<IP>.sslip.io:8080/admin (die IP deiner
VM). Erwartet: die Anmeldeseite des Realms master.
Melde dich mit admin und lab-admin-pw-123
an. Oben steht ein gelber Balken: Du bist als temporärer Admin
angemeldet.
Der Balken ist ernst gemeint. Ein Admin, dessen Passwort in einer Compose-Datei steht, gehört ersetzt. Das erledigst du in Drill 6, mit der Kommandozeile.
Fortschritt speichern? Kostenlos registrieren
Drill 4: kcadm.sh
grep -A3 '^kcadm()' ~/kc-lab/setup/env.sh
kcadm config credentials --server http://localhost:8080 --realm master \
--user admin --password lab-admin-pw-123
kcadm get realms --fields realm,enabledErwartet:
kcadm() {
docker compose -f "$LAB/keycloak/compose.yaml" exec -T keycloak \
/opt/keycloak/bin/kcadm.sh "$@"
}
Logging into http://localhost:8080 as user admin of realm master
[ {
"realm" : "master",
"enabled" : true
} ]
kcadm läuft im Container und spricht Keycloak über
localhost:8080 an. Die Anmeldung merkt es sich in einer
Datei im Container, bis der Container neu erzeugt wird.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Der Realm lab
kcadm create realms -s realm=lab -s enabled=true -s displayName="notes Labor"
kcadm get realms/lab --fields realm,displayName,sslRequired,accessTokenLifespan
curl -s $KC_URL/realms/lab/.well-known/openid-configuration \
| jq -r '.issuer, .authorization_endpoint, .token_endpoint, .jwks_uri'Erwartet (gekürzt):
Created new realm with id 'lab'
{
"realm" : "lab",
"displayName" : "notes Labor",
"accessTokenLifespan" : 300,
"sslRequired" : "external"
}
http://kc.192.168.64.7.sslip.io:8080/realms/lab
http://kc.192.168.64.7.sslip.io:8080/realms/lab/protocol/openid-connect/auth
http://kc.192.168.64.7.sslip.io:8080/realms/lab/protocol/openid-connect/token
http://kc.192.168.64.7.sslip.io:8080/realms/lab/protocol/openid-connect/certs
Jeder Realm hat sein eigenes Discovery-Dokument. Darin steht alles,
was eine Anwendung für den Login braucht.
sslRequired: external erlaubt HTTP nur aus privaten Netzen;
die VM liegt in einem, darum genügt bis Tag 12 HTTP.
In der Konsole wechselst du oben links über Manage realms in den neuen Realm.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Ein dauerhafter Admin
kcadm create users -r master -s username=kcadmin -s enabled=true \
-s [email protected] -s emailVerified=true
kcadm set-password -r master --username kcadmin --new-password lab-admin-pw-123
kcadm add-roles -r master --uusername kcadmin --rolename admin
kcloginErwartet (gekürzt):
Created new user with id '86794e71-…'
Logging into http://localhost:8080 as user kcadmin of realm master
kclogin aus env.sh meldet
kcadm als kcadmin an. Jetzt den temporären
Admin löschen:
kcadm get users -r master -q username=admin --fields username
ID=$(kcadm get users -r master -q username=admin -q exact=true \
--fields id --format csv --noquotes)
kcadm delete users/$ID -r master && echo "admin gelöscht"
kcadm get users -r master --fields usernameErwartet:
[ {
"username" : "admin"
}, {
"username" : "kcadmin"
} ]
admin gelöscht
[ {
"username" : "kcadmin"
} ]
Die erste Suche zeigt die Falle: -q username=admin sucht
nach Teilen des Namens und findet auch kcadmin. Mit
-q exact=true trifft es nur den einen. In der Konsole ist
der gelbe Balken nach erneuter Anmeldung als kcadmin
verschwunden.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Alles steht in Postgres
docker compose exec kc-db psql -U keycloak -d keycloak \
-c "select name, enabled from realm order by name"
docker compose restart keycloak
sleep 30
curl -s $KC_URL/realms/lab | jq -r .realmErwartet:
name | enabled
--------+---------
lab | t
master | t
(2 rows)
Container keycloak-keycloak-1 Started
lab
Keycloak selbst ist zustandslos; Realms, Benutzer und Clients liegen
in Postgres. Nach einem Neustart muss kcadm sich nicht neu
anmelden, nach einem docker compose up mit neuem Container
schon (kclogin).
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -s localhost:9000/health/ready | jq -r .statusErwartet: Keycloak ist bereit.
UP
kcadm get realms --fields realmErwartet: zwei Realms.
[ {
"realm" : "lab"
}, {
"realm" : "master"
} ]
kcadm get users -r master --fields usernameErwartet: nur noch der dauerhafte Admin.
[ {
"username" : "kcadmin"
} ]
Challenge
Access Tokens im Realm lab sollen nur zwei Minuten
gelten statt fünf. Stell es mit kcadm um und prüfe es.
Hinweis: Das Feld kennst du aus Drill 5;
kcadm update setzt Felder mit -s.
Lösung
kcadm update realms/lab -s accessTokenLifespan=120
kcadm get realms/lab --fields accessTokenLifespanErwartet:
{
"accessTokenLifespan" : 120
}
Kurze Tokens begrenzen den Schaden, wenn eines gestohlen wird. Den Preis zahlt die Anwendung: Sie muss öfter erneuern (Refresh Token, Tag 3).
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Admin-Zugang: Den Realm
masternur für Admins benutzen, Admins mit MFA (Tag 10) und die Admin-Konsole nicht ins Internet (KC_HOSTNAME_ADMIN, Tag 12). - Datenbank: Postgres gehört gesichert und hochverfügbar; Keycloak-Instanzen lassen sich dann beliebig ersetzen.
- Build-Optionen: In Produktion baut man ein eigenes
Image mit
kc.sh buildund startet mitstart --optimized; das spart Startzeit. - Bootstrap-Variablen nach dem ersten Start entfernen, sonst steht ein Passwort in der Konfiguration, das niemand mehr braucht.