Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 8: Keycloak-Provider – Login als Code

Ziel: Keycloak mit OpenTofu starten und in einer zweiten Konfiguration einrichten: Realm, Rolle, Client und Benutzer für notes. Dabei lernen, warum ein Provider nicht von Ressourcen derselben Konfiguration abhängen sollte, und wie eine Konfiguration die Ausgaben einer anderen liest. · Dauer: ca. 90 min · Voraussetzung: Tag 7

Briefing

  • Der Keycloak-Provider verwaltet Realms, Clients, Rollen, Gruppen und Benutzer über die Admin-API von Keycloak.
  • Ein Provider wird vor dem Plan konfiguriert. Hängen seine Zugangsdaten an einer Ressource, die erst im selben Lauf entsteht, gibt es beim ersten Plan nichts, womit er sich verbinden könnte. Darum zwei Konfigurationen: server startet Keycloak, config richtet es ein.
  • data "terraform_remote_state" liest die Outputs einer anderen Konfiguration – hier die Adresse des Servers.
 tag08/server  (Provider docker)    ─► Container keycloak :8180 ─► Output url
 tag08/config  (Provider keycloak)  ─► liest url per terraform_remote_state
                                    ─► Realm notes, Rolle, Client, Benutzer anna

Drill 1: Keycloak als Container

mkdir -p ~/tf-lab/tag08/server && cd ~/tf-lab/tag08/server
cat > main.tf <<'EOF'
terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 4.6"
    }
  }
}

provider "docker" {}

variable "admin_passwort" {
  type      = string
  sensitive = true
  default   = "lab-admin-pw-123"
}

resource "docker_image" "keycloak" {
  name         = "quay.io/keycloak/keycloak:26.8.1"
  keep_locally = true
}

locals {
  bereit = join(" && ", [
    "exec 3<>/dev/tcp/127.0.0.1/9000",
    "printf 'GET /health/ready HTTP/1.0\\r\\n\\r\\n' >&3",
    "grep -q UP <&3",
  ])
}

resource "docker_container" "keycloak" {
  name    = "keycloak-tag08"
  image   = docker_image.keycloak.image_id
  command = ["start-dev"]
  env = [
    "KC_BOOTSTRAP_ADMIN_USERNAME=admin",
    "KC_BOOTSTRAP_ADMIN_PASSWORD=${var.admin_passwort}",
    "KC_HEALTH_ENABLED=true",
  ]
  ports {
    internal = 8080
    external = 8180
    ip       = "127.0.0.1"
  }
  healthcheck {
    test     = ["CMD-SHELL", local.bereit]
    interval = "5s"
    retries  = 60
  }
  wait         = true
  wait_timeout = 300
}

output "url" {
  value = "http://127.0.0.1:8180"
}
EOF
tofu init -no-color >/dev/null
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
curl -s http://127.0.0.1:8180/realms/master | jq -r .realm

Erwartet (beim ersten Mal mit Download einige Minuten):

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
master

start-dev startet Keycloak ohne externe Datenbank – fürs Labor genug. Der Healthcheck fragt den Management-Port 9000, wait = true lässt OpenTofu warten, bis Keycloak bereit ist.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Eine zweite Konfiguration

mkdir -p ~/tf-lab/tag08/config && cd ~/tf-lab/tag08/config
cat > versions.tf <<'EOF'
terraform {
  required_providers {
    keycloak = {
      source  = "keycloak/keycloak"
      version = "~> 5.10"
    }
  }
}

data "terraform_remote_state" "server" {
  backend = "local"
  config = {
    path = "${path.module}/../server/terraform.tfstate"
  }
}

variable "admin_passwort" {
  type      = string
  sensitive = true
  default   = "lab-admin-pw-123"
}

provider "keycloak" {
  url       = data.terraform_remote_state.server.outputs.url
  realm     = "master"
  client_id = "admin-cli"
  username  = "admin"
  password  = var.admin_passwort
}
EOF
tofu init -no-color | grep -E 'Installed|initialized'
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
echo 'data.terraform_remote_state.server.outputs.url' | tofu console

Erwartet:

- Installed keycloak/keycloak v5.10.0 (signed, key ID A63FAED146E27E2A)
OpenTofu has been successfully initialized!
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
"http://127.0.0.1:8180"

Das erste apply legt nichts an, liest aber die Datenquelle und speichert sie im State – vorher wüsste die Konsole nur „(known after apply)“.

Der Provider bekommt seine Adresse aus dem State der Server-Konfiguration. Die beiden Konfigurationen sind nur über diese eine Schnittstelle gekoppelt: die Outputs. Wer den Server woanders startet, ändert nur dort etwas.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Realm, Rolle, Client, Benutzer

cat > realm.tf <<'EOF'
resource "keycloak_realm" "notes" {
  realm        = "notes"
  enabled      = true
  display_name = "notes"
}

resource "keycloak_role" "schreiben" {
  realm_id    = keycloak_realm.notes.id
  name        = "notes-schreiben"
  description = "Darf Notizen anlegen"
}

resource "keycloak_openid_client" "cli" {
  realm_id                     = keycloak_realm.notes.id
  client_id                    = "notes-cli"
  access_type                  = "CONFIDENTIAL"
  client_secret                = "lab-client-secret-123"
  direct_access_grants_enabled = true
  standard_flow_enabled        = false
}

resource "keycloak_user" "anna" {
  realm_id       = keycloak_realm.notes.id
  username       = "anna"
  email          = "[email protected]"
  email_verified = true
  first_name     = "Anna"
  last_name      = "Lab"
  initial_password {
    value     = "lab-user-pw-123"
    temporary = false
  }
}
EOF
cat > rollen.tf <<'EOF'
resource "keycloak_user_roles" "anna" {
  realm_id = keycloak_realm.notes.id
  user_id  = keycloak_user.anna.id
  role_ids = [keycloak_role.schreiben.id]
}
EOF
tofu apply -auto-approve -no-color | grep -E 'Apply complete'

Erwartet:

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Ein vollständiger Realm aus Code, ohne einen Klick in der Admin-Konsole. Ob er funktioniert, zeigt ein Token für anna:

K=http://127.0.0.1:8180
URL=$K/realms/notes/protocol/openid-connect/token
T=$(curl -s $URL -d grant_type=password -d client_id=notes-cli \
  -d client_secret=lab-client-secret-123 -d username=anna -d password=lab-user-pw-123 \
  | jq -r .access_token)
echo "$T" | jq -R 'split(".")[1] | @base64d | fromjson | .realm_access'

Erwartet:

{
  "roles": [
    "notes-schreiben"
  ]
}
  • Der curl-Aufruf ist ein Login mit Benutzername und Passwort (Password Grant): Client-ID und -Secret, dazu annas Zugangsdaten. Die Antwort ist JSON, jq -r holt das Token heraus.
  • Ein Token (JWT) besteht aus drei Teilen, getrennt durch Punkte. Der mittlere ist Base64-kodiertes JSON. jq -R liest das Token als Text, split teilt es, @base64d dekodiert, fromjson macht wieder JSON daraus.
  • Das Token enthält die Rolle notes-schreiben – genau das, was notes-api zum Anlegen prüft.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Drift in Keycloak

Jemand ändert den Anzeigenamen in der Konsole – hier per Admin-API:

A=$(curl -s -d grant_type=password -d client_id=admin-cli -d username=admin \
  -d password=lab-admin-pw-123 \
  $K/realms/master/protocol/openid-connect/token | jq -r .access_token)
curl -s -X PUT -H "Authorization: Bearer $A" -H 'Content-Type: application/json' \
  -d '{"displayName":"von Hand geändert"}' $K/admin/realms/notes
tofu plan -no-color | grep -E 'display_name|Plan:'
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
curl -s http://127.0.0.1:8180/realms/notes | jq -r .realm

Erwartet:

      ~ display_name                             = "von Hand geändert" -> "notes"
Plan: 0 to add, 1 to change, 0 to destroy.
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
notes

Wie bei Docker und Kubernetes: Der Code gewinnt. Teams, die Keycloak mit OpenTofu verwalten, sperren die Admin-Konsole für Änderungen an diesen Realms – oder holen jede Änderung in den Code.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Wer was abbaut

tofu plan -destroy -no-color | grep 'Plan:'
cd ../server && tofu plan -destroy -no-color | grep 'Plan:'

Erwartet:

Plan: 0 to add, 0 to change, 5 to destroy.
Plan: 0 to add, 0 to change, 2 to destroy.

Jede Konfiguration räumt nur ab, was in ihrem State steht. Die Reihenfolge ist wichtig: erst config, dann server. Umgekehrt fände der Keycloak-Provider beim Abbau keinen Keycloak mehr – und der State von config bliebe mit fünf verwaisten Einträgen zurück.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cd ~/tf-lab/tag08/config && tofu state list | wc -l

Erwartet: fünf Ressourcen und die Datenquelle.

6
curl -s http://127.0.0.1:8180/realms/notes | jq -r .realm

Erwartet:

notes
tofu plan -detailed-exitcode -no-color >/dev/null; echo "Exit: $?"

Erwartet:

Exit: 0

Challenge

Rollen sollen nicht an einzelnen Benutzern hängen, sondern an einer Gruppe schreiber. Leg die Gruppe mit der Rolle an, steck anna hinein und entferne die direkte Rollenzuordnung. Im Token muss die Rolle trotzdem stehen.

Hinweis: keycloak_group, keycloak_group_roles, keycloak_user_groups.

Lösung

cat > gruppe.tf <<'EOF'
resource "keycloak_group" "schreiber" {
  realm_id = keycloak_realm.notes.id
  name     = "schreiber"
}

resource "keycloak_group_roles" "schreiber" {
  realm_id = keycloak_realm.notes.id
  group_id = keycloak_group.schreiber.id
  role_ids = [keycloak_role.schreiben.id]
}

resource "keycloak_user_groups" "anna" {
  realm_id  = keycloak_realm.notes.id
  user_id   = keycloak_user.anna.id
  group_ids = [keycloak_group.schreiber.id]
}
EOF
rm rollen.tf
tofu apply -auto-approve -no-color | grep -E 'Apply complete'
T=$(curl -s $URL -d grant_type=password -d client_id=notes-cli \
  -d client_secret=lab-client-secret-123 -d username=anna -d password=lab-user-pw-123 \
  | jq -r .access_token)
echo "$T" | jq -R 'split(".")[1] | @base64d | fromjson | .realm_access'

Erwartet:

Apply complete! Resources: 3 added, 0 changed, 1 destroyed.
{
  "roles": [
    "notes-schreiben"
  ]
}

Die direkte Zuordnung lag in einer eigenen Datei – rm rollen.tf entfernt sie aus dem Code, OpenTofu entfernt sie aus Keycloak. OpenTofu legt die Gruppe an und entfernt die direkte Rolle im selben Lauf. Die Reihenfolge innerhalb eines Laufs ist nicht garantiert – wer eine Lücke vermeiden muss, macht zwei Schritte: erst Gruppe, dann Rolle entfernen.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Zugang des Providers: Statt des Admin-Kontos mit Passwort nutzt man einen eigenen Client mit Service-Account und nur den nötigen Rollen von realm-management.
  • Remote State statt Datei-Pfad: Mit einem gemeinsamen Backend (Tag 9) liest terraform_remote_state aus S3 statt aus einer lokalen Datei – das funktioniert dann auch in der CI.
  • Benutzer gehören selten in den Code: Realms, Clients, Rollen und Gruppen ja; echte Benutzer kommen aus einem Verzeichnis (LDAP, AD) oder melden sich selbst an.