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 userubuntuin~/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.iobecomes192.168.64.7. No/etc/hosts, no DNS of your own. - notes consists of
notes-api(Go) andnotes-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 IPv4Expected (abridged, your IP will differ):
Launched: kc
IPv4: 192.168.64.7
export KC_IP=192.168.64.7
ssh ubuntu@$KC_IPFrom 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 ubuntuLog 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-60Expected:
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 NameExpected (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/hoststhere.
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 notesExpected (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.goExpected: 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.goExpected:
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.comand 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, neverlatest; Keycloak has changes in minor versions that require an upgrade (Day 12).