Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 13: Automatisierung mit REST, kcadm.sh und Terraform

Ziel: Keycloak ohne Konsole verwalten: mit einem Service-Account über die Admin REST API, und deklarativ mit Terraform – inklusive Drift und Import von Bestehendem. · Dauer: ca. 90 min · Voraussetzung: Tag 12

Briefing

  • Alles, was die Admin-Konsole kann, geht über die Admin REST API unter /admin/realms/<realm>/…. Die Konsole ist selbst nur ein Client dieser API.
  • Automatisierung meldet sich nicht als Mensch an, sondern als Service-Account eines Clients (Client Credentials Grant). Was er darf, bestimmen Client-Rollen von realm-management: view-users, manage-users, manage-clients, manage-realm …
  • kcadm.sh ist ein bequemer Wrapper um diese API – gut für Skripte und Fehlersuche.
  • Terraform beschreibt den Sollzustand. plan zeigt den Unterschied zum Istzustand, apply stellt ihn her. Änderungen von Hand (Drift) fallen beim nächsten Plan auf.
 curl / kcadm.sh / Terraform ─Client Credentials─► Token (automation, realm-management)
        └──────────────── Admin REST API /admin/realms/lab/… ──────────────────┘

Drill 1: Ein Service-Account

source ~/kc-lab/setup/env.sh
mkdir -p ~/kc-lab/tag13
kclogin
kcadm create clients -r lab -s clientId=automation -s secret=lab-client-secret-123 \
  -s serviceAccountsEnabled=true -s standardFlowEnabled=false \
  -s directAccessGrantsEnabled=false
kcadm add-roles -r lab --uusername service-account-automation \
  --cclientid realm-management --rolename view-users --rolename view-realm
bot() { curl -s -d grant_type=client_credentials -d client_id=automation \
  -d client_secret=lab-client-secret-123 \
  $KC_URL/realms/lab/protocol/openid-connect/token | jq -r .access_token; }
jwt "$(bot)" | jq -c '.resource_access["realm-management"]'

Erwartet:

Logging into http://localhost:8080 as user kcadmin of realm master
Created new client with id '…'
{"roles":["view-realm","view-users","query-groups","query-users"]}

Der Client hat keinen Login-Flow, nur einen Service-Account. Den Benutzer dazu legt Keycloak selbst an: service-account-automation. view-users bringt query-users und query-groups als Composite mit.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Die Admin REST API mit curl

A=$KC_URL/admin/realms/lab
T=$(bot)
curl -s -H "Authorization: Bearer $T" "$A/users?username=anna&exact=true" \
  | jq -c '.[] | {username, email}'
curl -s -H "Authorization: Bearer $T" "$A/users/count"; echo
RITA='{"username":"rita","enabled":true,"email":"[email protected]","emailVerified":true,
  "firstName":"Rita","lastName":"Rest"}'
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $T" \
  -H 'Content-Type: application/json' -d "$RITA" $A/users

Erwartet:

{"username":"anna","email":"[email protected]"}
10
403

Lesen darf der Bot, anlegen nicht. Wir geben ihm manage-users – und brauchen danach ein neues Token, denn Rollen stehen im Token:

kcadm add-roles -r lab --uusername service-account-automation \
  --cclientid realm-management --rolename manage-users
T=$(bot)
curl -s -D - -o /dev/null -H "Authorization: Bearer $T" \
  -H 'Content-Type: application/json' -d "$RITA" $A/users | grep -i -E '^HTTP|^location'
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $T" \
  -H 'Content-Type: application/json' -d "$RITA" $A/users

Erwartet:

HTTP/2 201 
location: https://kc.192.168.64.5.sslip.io/admin/realms/lab/users/…
409
  • 201 Created liefert keinen Body, die ID steht im Header Location.
  • Der zweite Versuch gibt 409 Conflict: rita gibt es schon. Ein Skript, das zweimal laufen darf, fragt vorher nach oder wertet 409 als „schon erledigt”.
  • kcadm macht dasselbe: kcadm create users schickt genau diesen POST.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Terraform einrichten

sudo apt-get install -y unzip >/dev/null
V=1.17.1; ARCH=$(dpkg --print-architecture)
cd ~/kc-lab/tag13
U=https://releases.hashicorp.com/terraform/${V}
curl -sSLO $U/terraform_${V}_linux_${ARCH}.zip
curl -sSL $U/terraform_${V}_SHA256SUMS \
  | grep "linux_${ARCH}.zip" | sha256sum -c
sudo unzip -o -q terraform_${V}_linux_${ARCH}.zip terraform -d /usr/local/bin
terraform version | head -1

Erwartet:

terraform_1.17.1_linux_amd64.zip: OK
Terraform v1.17.1

Auf einem Mac mit Apple Silicon steht dort arm64. Terraform verwaltet Rollen, Clients und Benutzer – dafür braucht der Bot mehr Rechte:

kcadm add-roles -r lab --uusername service-account-automation \
  --cclientid realm-management --rolename manage-clients --rolename manage-realm
cp -R ~/kc-lab/code/terraform ~/kc-lab/terraform && cd ~/kc-lab/terraform
ls
sed -n '/^provider/,/^}/p' versions.tf

Erwartet:

main.tf
variables.tf
versions.tf
provider "keycloak" {
  url           = var.kc_url
  realm         = "lab"
  client_id     = "automation"
  client_secret = var.client_secret
}

Der Provider meldet sich wie unser curl als automation an. Die Adresse und das Secret kommen aus Variablen, das Secret steht damit nicht im Code. Terraform liest sie aus Umgebungsvariablen mit dem Präfix TF_VAR_:

export TF_VAR_kc_url=$KC_URL TF_VAR_client_secret=lab-client-secret-123
terraform init -no-color | grep -E 'Installed|successfully'

Erwartet:

- Installed keycloak/keycloak v5.10.0 (self-signed, key ID A63FAED146E27E2A)
Terraform has been successfully initialized!

Fortschritt speichern? Kostenlos registrieren

Drill 4: Plan und Apply

main.tf beschreibt Berichte für notes: eine Rolle notes-berichte, eine Gruppe berichte mit dieser Rolle, einen Client notes-reports und den Benutzer theo in der Gruppe.

grep -E '^(resource|data)' main.tf
terraform plan -no-color | grep -E 'will be created|Plan:'

Erwartet:

data "keycloak_realm" "lab" {
resource "keycloak_role" "berichte" {
resource "keycloak_group" "berichte" {
resource "keycloak_group_roles" "berichte" {
resource "keycloak_openid_client" "reports" {
resource "keycloak_user" "theo" {
resource "keycloak_user_groups" "theo" {
  # keycloak_group.berichte will be created
  # keycloak_group_roles.berichte will be created
  # keycloak_openid_client.reports will be created
  # keycloak_role.berichte will be created
  # keycloak_user.theo will be created
  # keycloak_user_groups.theo will be created
Plan: 6 to add, 0 to change, 0 to destroy.
terraform apply -auto-approve -no-color | grep -E 'Apply complete'
terraform plan -no-color | tail -2
jwt "$(token theo lab-user-pw-theo)" \
  | jq -c '[.realm_access.roles[] | select(startswith("notes"))]'

Erwartet:

Apply complete! Resources: 6 added, 0 changed, 0 destroyed.
Terraform has compared your real infrastructure against your configuration
and found no differences, so no changes are needed.
["notes-berichte"]

Terraform hat die Abhängigkeiten selbst sortiert: erst Rolle und Gruppe, dann die Zuordnung. Der zweite Plan findet nichts mehr zu tun. Was Terraform verwaltet, steht in der Datei terraform.tfstate – samt Secrets und Passwörtern im Klartext. In Projekten gehört der State in ein geschütztes Backend, nie ins Git.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Jemand ändert etwas von Hand

RC=$(terraform output -raw reports_client_uuid)
kcadm update clients/$RC -r lab -s 'name=von Hand geändert'
terraform plan -no-color | grep -E '~ name|will be updated|Plan:'
terraform apply -auto-approve -no-color | grep -E 'Apply complete'
kcadm get clients/$RC -r lab | jq -r .name

Erwartet:

  # keycloak_openid_client.reports will be updated in-place
      ~ 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 Berichte

Der Code gewinnt. Wer Keycloak mit Terraform verwaltet, ändert diese Objekte nicht mehr in der Konsole – oder holt die Änderung in den Code.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Bestehendes übernehmen

Die Gruppe leser aus Tag 2 gibt es schon. Terraform kann sie übernehmen, statt sie neu anzulegen. Ein import-Block nennt die ID, -generate-config-out schreibt den passenden Code gleich mit:

GID=$(kcadm get groups -r lab -q search=leser \
  | jq -r '.[] | select(.name=="leser") | .id')
printf 'import {\n  to = keycloak_group.leser\n  id = "lab/%s"\n}\n' "$GID" > import.tf
terraform plan -no-color -generate-config-out=leser.tf \
  | grep -E 'will be imported|Plan:'
grep -v '^#' leser.tf
terraform apply -auto-approve -no-color | grep -E 'Apply complete'
terraform state list | grep leser

Erwartet:

  # keycloak_group.leser will be imported
Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.
resource "keycloak_group" "leser" {
  attributes      = {}
  description     = null
  name            = "leser"
  organization_id = null
  parent_id       = null
  realm_id        = "lab"
}
Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.
keycloak_group.leser

Die Import-ID hat beim Keycloak-Provider die Form <realm>/<id>. Den erzeugten Code räumt man danach auf, zum Beispiel realm_id auf data.keycloak_realm.lab.id.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

terraform state list | wc -l

Erwartet: Datenquelle, sechs Ressourcen und die importierte Gruppe.

8
terraform plan -no-color -detailed-exitcode >/dev/null; echo "exit=$?"

Erwartet: Code und Keycloak stimmen überein (0 = keine Änderungen).

exit=0
kcadm get users -r lab -q username=rita -q exact=true | jq -r '.[0].email'

Erwartet:

[email protected]

Challenge

Der Client notes-reports soll Berichte ohne Benutzer abrufen: Sein Service-Account braucht die Rolle notes-berichte. Lös das mit Terraform und zeig die Rolle im Token.

Hinweis: Die Ressource heißt keycloak_openid_client_service_account_realm_role, die ID des Service-Account-Benutzers liefert keycloak_openid_client.reports.

Lösung

cat > challenge.tf <<'EOF'
resource "keycloak_openid_client_service_account_realm_role" "reports" {
  realm_id                = data.keycloak_realm.lab.id
  service_account_user_id = keycloak_openid_client.reports.service_account_user_id
  role                    = keycloak_role.berichte.name
}
EOF
terraform apply -auto-approve -no-color | grep -E 'Apply complete'
T=$(curl -s -d grant_type=client_credentials -d client_id=notes-reports \
  -d client_secret=lab-client-secret-123 \
  $KC_URL/realms/lab/protocol/openid-connect/token | jq -r .access_token)
jwt "$T" | jq -c '[.realm_access.roles[] | select(startswith("notes"))]'

Erwartet:

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
["notes-berichte"]

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Geringste Rechte: Ein eigener Automatisierungs-Client pro Realm und Zweck, nur mit den Rollen, die er braucht. manage-realm ist fast Admin.
  • Realms anlegen darf nur ein Konto im Realm master (Rolle create-realm). Für ganze Umgebungen bekommt Terraform dort einen eigenen Service-Account.
  • State: Remote-Backend mit Verschlüsselung und Locking (S3, GitLab, Terraform Cloud). Secrets besser aus einem Vault lesen als in .tf-Dateien schreiben.
  • Alternativen: Der keycloak-config-cli spielt Realm-JSON idempotent ein; der Operator (Tag 14) kann Realms per KeycloakRealmImport anlegen, aber nicht pflegen.
  • OpenTofu versteht dieselbe Konfiguration und denselben Provider.