open-how2 – Entdecke. Verstehe. Nutze.
Veröffentlicht am
• How2-Tipps

Keycloak REST-API – Benutzerverwaltung automatisieren

Autor
Keycloak REST-API – Benutzerverwaltung automatisieren

Die Verwaltung von Benutzern, Gruppen und Rollen gehört zu den wiederkehrenden Aufgaben in jedem Identity-Management-System. Wer regelmäßig Accounts anlegt, Passwörter zurücksetzt oder Rechte ändert, weiß: Das kann zeitaufwendig und fehleranfällig sein.

Mit der Keycloak REST-API lässt sich all das automatisieren – von der Benutzeranlage bis zur Rollenzuweisung. Dieser Artikel zeigt, wie Admins und DevOps die API in Skripten und Tools einsetzen können, um Keycloak effizient zu steuern.

Was ist die Keycloak REST-API?

Keycloak stellt eine umfangreiche REST-Schnittstelle bereit, über die nahezu alle Funktionen der Admin-Oberfläche automatisiert werden können – und das per HTTP-Requests.

Die API folgt den Prinzipien von REST:

  • Ressourcen (z. B. Benutzer, Gruppen, Realms) sind über eindeutige URLs erreichbar
  • Aktionen erfolgen per GET, POST, PUT und DELETE
  • Authentifizierung erfolgt über Access Tokens

Die Schnittstelle ist ideal für:

  • automatisierte Benutzer- und Gruppenverwaltung
  • CI/CD-Integrationen
  • DevOps-Workflows
  • Onboarding-Prozesse in großen Organisationen

Voraussetzungen

Bevor du die REST-API verwenden kannst, brauchst du:

  1. Keycloak-Installation (z. B. unter https://keycloak.example.de)
  2. Ein Admin-Konto oder einen Benutzer mit API-Berechtigungen
  3. Ein Tool für API-Requests – z. B.:
  • curl (Kommandozeile)
  • Postman (GUI)
  • Python-Skript mit requests

Schritt 1: Access Token abrufen

Um mit der API zu arbeiten, brauchst du ein gültiges Access Token. Das Token erhältst du durch einen POST-Request an den Token-Endpunkt:

curl --location --request POST 'https://keycloak.example.de/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=admin-cli' \
--data-urlencode 'username=admin' \
--data-urlencode 'password=MeinSicheresPasswort' \
--data-urlencode 'grant_type=password'

Die Antwort enthält dein Token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 60,
  "refresh_token": "...",
  "token_type": "Bearer"
}

Dieses Token nutzt du für alle folgenden API-Aufrufe.

Schritt 2: Benutzer anlegen

Nun kannst du neue Benutzer automatisch anlegen:

curl -X POST \
  https://keycloak.example.de/admin/realms/organisation/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "username": "m.mueller",
        "email": "m.mueller@example.de",
        "firstName": "Max",
        "lastName": "Müller",
        "enabled": true
      }'

Antwort bei Erfolg: HTTP 201 Created

Schritt 3: Passwort setzen

Nach dem Anlegen eines Benutzers kannst du ein Passwort hinzufügen:

curl -X PUT \
  https://keycloak.example.de/admin/realms/organisation/users/<USER_ID>/reset-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "type": "password",
        "value": "MeinNeuesPasswort123!",
        "temporary": false
      }'

Tipp: Die USER_ID erhältst du über einen GET-Request auf /users?username=m.mueller.

Schritt 4: Rollen zuweisen

Rollen können programmgesteuert zugewiesen werden – z. B. die Rolle „editor“:

curl -X POST \
  https://keycloak.example.de/admin/realms/organisation/users/<USER_ID>/role-mappings/realm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '[
        {
          "id": "b12345f7-6789-4a0d-bd1a-3f6a9e111a22",
          "name": "editor"
        }
      ]'

Damit lassen sich automatisch Zugriffsrechte für neu angelegte Accounts vergeben.

Schritt 5: Benutzer synchronisieren oder löschen

Auch Synchronisation und Löschung lassen sich einfach automatisieren.

Benutzer synchronisieren:

curl -X POST \
  https://keycloak.example.de/admin/realms/organisation/user-storage/<LDAP_ID>/sync?action=triggerFullSync \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Benutzer löschen:

curl -X DELETE \
  https://keycloak.example.de/admin/realms/organisation/users/<USER_ID> \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

So kannst du z. B. täglich Benutzer automatisch aus LDAP aktualisieren oder Inaktive entfernen.

Integration in Skripte (Beispiel Python)

Mit der Python-Bibliothek requests lässt sich die API bequem in Automatisierungen einbauen:

import requests

url = "https://keycloak.example.de/admin/realms/organisation/users"
headers = {"Authorization": f"Bearer {ACCESS_TOKEN}", "Content-Type": "application/json"}
data = {
    "username": "a.schulz",
    "email": "a.schulz@example.de",
    "firstName": "Anna",
    "lastName": "Schulz",
    "enabled": True
}
response = requests.post(url, headers=headers, json=data)
print(response.status_code)

Ideal für CI/CD-Pipelines oder Onboarding-Workflows.

Weitere API-Endpunkte

  • /users – Benutzerverwaltung
  • /groups – Gruppenmanagement
  • /clients – Anwendungsdefinitionen
  • /roles – Rollen und Berechtigungen
  • /user-storage – LDAP/AD-Anbindung

Offizielle Dokumentation: 👉 https://www.keycloak.org/docs-api/

Mit der Keycloak REST-API lassen sich selbst komplexe Benutzer- und Rollenprozesse vollautomatisieren. Ob du neue Mitarbeiter anlegst, Onboarding-Prozesse implementierst oder CI/CD-Workflows erweiterst – mit der API sparst du Zeit, reduzierst Fehler und erhöhst die Sicherheit.

Keycloak ist nicht nur ein Login-System, sondern eine mächtige Plattform für automatisiertes Identity Management.

Ähnliche Beiträge