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.shist ein bequemer Wrapper um diese API – gut für Skripte und Fehlersuche.- Terraform beschreibt den Sollzustand.
planzeigt den Unterschied zum Istzustand,applystellt 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/usersErwartet:
{"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/usersErwartet:
HTTP/2 201
location: https://kc.192.168.64.5.sslip.io/admin/realms/lab/users/…
409
201 Createdliefert keinen Body, die ID steht im HeaderLocation.- 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”. kcadmmacht dasselbe:kcadm create usersschickt 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 -1Erwartet:
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.tfErwartet:
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 .nameErwartet:
# 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 leserErwartet:
# 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 -lErwartet: 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-realmist fast Admin. - Realms anlegen darf nur ein Konto im Realm
master(Rollecreate-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
KeycloakRealmImportanlegen, aber nicht pflegen. - OpenTofu versteht dieselbe Konfiguration und denselben Provider.