Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 0: Das Trainingsgelände

Ziel: Die Labor-VM anlegen, Docker und die Werkzeuge installieren, den Begleitcode holen, die Hostnamen über sslip.io prüfen und die Images von notes bauen. · Dauer: ca. 45 min · Voraussetzung: keine

Briefing

  • Gearbeitet wird in der Ubuntu-24.04-VM kc, als User ubuntu in ~/kc-lab.
  • Beim Login im Browser leitet Keycloak hin und her. Damit das klappt, muss Keycloak im Browser des Laptops und in den Containern unter demselben Namen erreichbar sein.
  • sslip.io löst jeden Namen, der eine IP enthält, auf genau diese IP auf: kc.192.168.64.7.sslip.io wird zu 192.168.64.7. Kein /etc/hosts, kein eigenes DNS.
  • notes besteht aus notes-api (Go) und notes-web (Node); ab Tag 4 steht davor oauth2-proxy.
 Laptop-Browser ──► kc.<IP>.sslip.io:8080 ──► VM kc: Keycloak
                ──► notes.<IP>.sslip.io:4180 ──► oauth2-proxy ─► notes-web ─► notes-api
                         Container fragen dieselben Namen, sslip.io liefert die VM-IP

Drill 1: Die Labor-VM

Auf dem Laptop (Multipass von multipass.run):

multipass launch 24.04 --name kc --cpus 2 --memory 4G --disk 30G
multipass exec kc -- bash -c "echo '$(cat ~/.ssh/id_ed25519.pub)' \
  >> ~/.ssh/authorized_keys"
multipass info kc | grep IPv4

Erwartet (gekürzt, die IP weicht bei dir ab):

Launched: kc
IPv4:           192.168.64.7
export KC_IP=192.168.64.7
ssh ubuntu@$KC_IP

Ab hier läuft alles in der VM.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Docker und Werkzeuge

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release; echo $VERSION_CODENAME) \
stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin jq ldap-utils
sudo usermod -aG docker ubuntu

Melde dich ab (exit) und wieder an, damit die Gruppe docker gilt:

docker --version
docker compose version
ldapsearch -VV 2>&1 | head -1 | cut -c1-60

Erwartet:

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1
ldapsearch: @(#) $OpenLDAP: ldapsearch 2.6.10+dfsg-0ubuntu0.24

ldap-utils bringt ldapsearch und ldapadd für Tag 6 mit.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Begleitcode und Umgebung

mkdir -p ~/kc-lab/setup
git clone https://github.com/thomaszachmann/keycloak-zum-anfassen.git ~/kc-lab/code
cp ~/kc-lab/code/setup/env.sh ~/kc-lab/setup/
source ~/kc-lab/setup/env.sh
echo "$VM_IP"
echo "$KC_URL"
echo "$NOTES_URL"

Erwartet (gekürzt, die IP weicht bei dir ab):

Cloning into '/home/ubuntu/kc-lab/code'...
192.168.64.7
http://kc.192.168.64.7.sslip.io:8080
http://notes.192.168.64.7.sslip.io:4180

env.sh nimmt die erste IP der VM. Hat deine VM mehrere, setz VM_IP vorher selbst.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Namen über sslip.io

getent hosts kc.$VM_IP.sslip.io
docker run --rm busybox:1.37 nslookup notes.$VM_IP.sslip.io | grep -A1 Name

Erwartet (gekürzt):

192.168.64.7    kc.192.168.64.7.sslip.io
Name:   notes.192.168.64.7.sslip.io
Address: 192.168.64.7

Die VM und ein Container lösen den Namen gleich auf. Der Laptop auch: Ruf http://kc.<IP>.sslip.io:8080 ab Tag 1 einfach im Browser auf.

Achtung: sslip.io braucht Internet. Manche Router filtern Antworten, die auf private Adressen zeigen („DNS-Rebinding-Schutz”). Löst der Name auf dem Laptop nicht auf, trag ihn dort in /etc/hosts ein.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Die Images von notes

cd ~/kc-lab/code/notes/notes-api
docker build -q --build-arg VERSION=0.4.0 -t notes-api:0.4.0 .
cd ~/kc-lab/code/notes/notes-web
docker build -q -t notes-web:0.2.0 .
docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}' | grep notes

Erwartet (gekürzt, beim ersten Mal einige Minuten):

sha256:61e412f5a19b…
sha256:54fc8202a72c…
notes-web:0.2.0 260MB
notes-api:0.4.0 16.4MB

Neu in notes-api 0.4.0: oidc.go. Ist NOTES_OIDC_ISSUER gesetzt, verlangt POST /notes statt des API-Keys ein gültiges Token von Keycloak mit der Rolle notes-schreiben, und GET /whoami zeigt, wer angemeldet ist. notes-web 0.2.0 reicht das Token von oauth2-proxy an die API weiter (Tag 4).

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

docker images notes-api --format '{{.Tag}}'

Erwartet: die Version mit OIDC.

0.4.0
getent hosts notes.$VM_IP.sslip.io | awk '{print $1}'

Erwartet: die IP deiner VM.

192.168.64.7
grep -c '^func verify\|func (o \*oidcConfig) verify' \
  ~/kc-lab/code/notes/notes-api/oidc.go

Erwartet: Die Prüfung der Tokens steckt im Code.

1

Challenge

Wie prüft notes-api eine Signatur, ohne Keycloak bei jeder Anfrage zu fragen? Finde in oidc.go die Stelle, an der die Schlüssel geholt werden, und wann sie neu geladen werden.

Hinweis: Such nach jwks_uri und nach fetched.

Lösung

cd ~/kc-lab/code/notes/notes-api
grep -n 'jwks_uri\|openid-configuration' oidc.go
grep -n 'time.Since(o.fetched)' oidc.go

Erwartet:

178:        JwksURI string `json:"jwks_uri"`
180:    if err := o.getJSON(ctx, o.issuer+"/.well-known/openid-configuration", &disc); err…
145:    if time.Since(o.fetched) < 10*time.Second {

notes-api fragt einmal das Discovery-Dokument, lädt daraus die öffentlichen Schlüssel (JWKS) und hält sie im Speicher. Neu geladen wird nur, wenn ein Token eine unbekannte kid trägt, etwa nach einem Schlüsselwechsel, und höchstens alle zehn Sekunden.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Echte Namen: sslip.io ist ein Laborwerkzeug. In Produktion bekommt Keycloak einen festen DNS-Namen wie login.example.com und ein Zertifikat (Tag 12).
  • Ein Name für alle: Der Aussteller (iss) steht in jedem Token. Ändert sich der Name, sind alle Tokens und Client-Einstellungen betroffen. Den Namen legt man einmal fest.
  • Images pinnen: quay.io/keycloak/keycloak:26.8.1, nie latest; Keycloak hat in Minor-Versionen Änderungen, die ein Upgrade erfordern (Tag 12).