Skip to content
Hands-on IT IT Drills

Day 0: The Training Ground

Goal: Create the lab VM, install Docker and the tools, fetch the companion code, check the hostnames via sslip.io and build the notes images. · Duration: approx. 45 min · Prerequisite: none

Briefing

  • You work in the Ubuntu 24.04 VM kc, as user ubuntu in ~/kc-lab.
  • During a browser login, Keycloak redirects back and forth. For that to work, Keycloak must be reachable under the same name in the laptop’s browser and inside the containers.
  • sslip.io resolves any name that contains an IP to exactly that IP: kc.192.168.64.7.sslip.io becomes 192.168.64.7. No /etc/hosts, no DNS of your own.
  • notes consists of notes-api (Go) and notes-web (Node); from Day 4 on, oauth2-proxy sits in front of it.
 Laptop browser ──► kc.<IP>.sslip.io:8080 ──► VM kc: Keycloak
                ──► notes.<IP>.sslip.io:4180 ──► oauth2-proxy ─► notes-web ─► notes-api
                         Containers ask for the same names, sslip.io returns the VM IP

Drill 1: The Lab VM

On the laptop (Multipass from 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

Expected (abridged, your IP will differ):

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

From here on, everything runs inside the VM.

Save your progress? Sign up for free

Drill 2: Docker and Tools

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

Log out (exit) and back in so that the docker group takes effect:

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

Expected:

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

ldap-utils brings ldapsearch and ldapadd for Day 6.

Save your progress? Sign up for free

Drill 3: Companion Code and Environment

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"

Expected (abridged, your IP will differ):

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 takes the VM’s first IP. If your VM has several, set VM_IP yourself beforehand.

Save your progress? Sign up for free

Drill 4: Names via sslip.io

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

Expected (abridged):

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

The VM and a container resolve the name the same way. So does the laptop: from Day 1 on, simply open http://kc.<IP>.sslip.io:8080 in the browser.

Warning: sslip.io needs internet access. Some routers filter answers that point to private addresses (“DNS rebinding protection”). If the name does not resolve on the laptop, add it to /etc/hosts there.

Save your progress? Sign up for free

Drill 5: The notes Images

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

Expected (abridged, a few minutes the first time):

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

New in notes-api 0.4.0: oidc.go. If NOTES_OIDC_ISSUER is set, POST /notes requires a valid token from Keycloak with the role notes-schreiben (write notes) instead of the API key, and GET /whoami shows who is logged in. notes-web 0.2.0 passes the token from oauth2-proxy on to the API (Day 4).

Save your progress? Sign up for free

Checkpoint

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

Expected: the version with OIDC.

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

Expected: your VM’s IP.

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

Expected: The token check is in the code.

1

Challenge

How does notes-api check a signature without asking Keycloak on every request? Find the place in oidc.go where the keys are fetched, and when they are reloaded.

Hint: Search for jwks_uri and for fetched.

Solution

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

Expected:

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 requests the discovery document once, loads the public keys (JWKS) from it and keeps them in memory. It only reloads when a token carries an unknown kid, for example after a key rotation, and at most every ten seconds.

Save your progress? Sign up for free

Enterprise Note

  • Real names: sslip.io is a lab tool. In production, Keycloak gets a fixed DNS name such as login.example.com and a certificate (Day 12).
  • One name for everyone: The issuer (iss) is in every token. If the name changes, all tokens and client settings are affected. You set the name once and keep it.
  • Pin images: quay.io/keycloak/keycloak:26.8.1, never latest; Keycloak has changes in minor versions that require an upgrade (Day 12).