Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Erster Start mit Postgres

Ziel: Keycloak im Produktionsmodus mit Postgres starten, Health und Metriken abfragen, die Admin-Konsole und kcadm.sh kennenlernen, den Realm lab anlegen 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. master verwaltet Keycloak selbst; Anwendungen bekommen eigene Realms.
  • start ist der Produktionsmodus: Datenbank, fester Hostname, ohne TLS nur mit KC_HTTP_ENABLED. start-dev (Kong-Buch) ist nur für Experimente.
  • Der erste Admin ist temporär. Er gehört ersetzt.
  • kcadm.sh ist die Kommandozeile für die Admin-API. env.sh stellt sie als kcadm bereit.
 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.

Anmeldeseite der Admin-Konsole im Realm master

Melde dich mit admin und lab-admin-pw-123 an. Oben steht ein gelber Balken: Du bist als temporärer Admin angemeldet.

Die Admin-Konsole mit dem Hinweis auf den temporären Admin

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,enabled

Erwartet:

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.

Der Realm lab mit seinem Anzeigenamen

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
kclogin

Erwartet (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 username

Erwartet:

[ {
  "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 .realm

Erwartet:

  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 .status

Erwartet: Keycloak ist bereit.

UP
kcadm get realms --fields realm

Erwartet: zwei Realms.

[ {
  "realm" : "lab"
}, {
  "realm" : "master"
} ]
kcadm get users -r master --fields username

Erwartet: 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 accessTokenLifespan

Erwartet:

{
  "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 master nur 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 build und startet mit start --optimized; das spart Startzeit.
  • Bootstrap-Variablen nach dem ersten Start entfernen, sonst steht ein Passwort in der Konfiguration, das niemand mehr braucht.