Foreword
Read little, type a lot. The Docker books built the
notes application, and in “Kong hands-on” it got a gateway.
What it still lacks is a login: Who are you, what are you allowed to do,
and how do you sign in without every application bringing its own user
management?
The answer is Keycloak. You learn it from the bottom up: first
Keycloak with Postgres, realms, users and roles, then OpenID Connect and
what is inside a token. notes gets a real login in the browser, and the
API checks tokens itself. After that, the users come from a directory:
from OpenLDAP and, for comparison, from an Active Directory with Samba.
Then come MFA, your own login flows, your own look, running behind TLS
with two instances, automation with REST, kcadm.sh and
Terraform, and finally the Keycloak Operator in Kubernetes.
The book is aimed at developers, platform and ops people who are confident with Docker and want to solve authentication centrally: single sign-on for their own applications, users from the company directory, MFA and an operation that holds up at night, too.
The Training Rules
- Type, don’t copy. Every command once yourself.
- Compare with Expected. After every drill you see what you should get. If it differs, that is where the real lesson is.
- Pass the checkpoint. Only when the check commands show what is listed there do you move on.
- Solve the challenge on your own. First the hint, then the solution.
- Lab values stay in the lab.
lab-admin-pw-123,lab-user-pw-123,lab-ldap-pw-123and all otherlab-…values are practice data. You never print real tokens, not even in the lab.
Warning: All output and images come from real test runs. IDs, times, IP addresses and keys will differ on your machine. What matters is what happens.
Structure of Each Training Day
| Section | Purpose |
|---|---|
| Briefing | The essentials in a few bullet points |
| Drills | Commands with expected output, images of the UI |
| Checkpoint | Individual check commands: did everything work? |
| Challenge | A task without instructions |
| Enterprise Note | What is different in production |
The Training Plan
| Part | Day | Unit |
|---|---|---|
| 1 – Fundamentals | 0 | The training ground |
| 1 | First start with Postgres | |
| 2 | Users, groups, roles | |
| 3 | OIDC and tokens | |
| 4 | notes with login | |
| 5 | Mappers, scopes, audience | |
| 2 – Directory | 6 | OpenLDAP |
| 7 | User federation with LDAP | |
| 8 | Groups and roles from LDAP | |
| 9 | Active Directory with Samba | |
| 3 – Security and customization | 10 | MFA, password policies, brute force protection |
| 11 | Flows, identity brokering, SAML, theme | |
| 4 – Operations | 12 | Proxy, TLS, two instances, export, upgrade |
| 13 | Automation | |
| 14 | Keycloak Operator on k3s | |
| Competition | 15 | Disaster drills |
| Appendix | A | Cheat sheet |
| B | Final exam |
The Lab
You work on an Ubuntu 24.04 VM kc with 2 CPUs and 4 GB
RAM, which you start with Multipass, via SSH on the VM. You open the
browser on your laptop. For Day 14, a VM k3s is added. Any
other Ubuntu VM with SSH, sudo and internet access will do
as well.
The tested versions: Keycloak 26.8.1 (also 26.8.0 for the upgrade
drills), Postgres 18.6, oauth2-proxy 7.15.5, OpenLDAP 2.6.10 from Debian
13, Samba 4.25.1, Caddy 2.11.7, Terraform 1.17.1 with the provider
keycloak/keycloak 5.10.0, k3s v1.36.5 and the Keycloak
Operator 26.8.1.
You can find the companion code at
https://github.com/thomaszachmann/keycloak-zum-anfassen;
Day 0 fetches it with git clone.
Where this book only touches on a topic, the sister books go deeper: “Docker Compose hands-on” for the backend, “Kong hands-on” for the gateway in front of the API, “Kubernetes hands-on” for Day 14.
Let’s go.