Worum es geht
Nicht jede Anfrage kommt von einem Menschen. Manchmal ruft ein Server einen anderen auf: CIAS legt Konten in Keycloak an, oder CDMS fragt CIAS, ob ein Mandant bedient werden darf. Dafür braucht der Server ein eigenes Token, ohne dass jemand ein Passwort eintippt.
Der Standardweg dafür heißt Client Credentials. Der Server meldet sich bei Keycloak mit der ID und dem Geheimnis seines Clients an und bekommt ein Access-Token. Ein Client ist in Keycloak der Eintrag für ein Programm.
Der Ablauf
sequenceDiagram
participant D as Dienst
participant K as Keycloak
participant A as API
D->>K: POST /token<br/>grant_type=client_credentials<br/>client_id, client_secret
K-->>D: Access-Token des Service-Accounts
D->>A: Anfrage mit Authorization: Bearer …
A-->>D: Antwort
Note over D: merkt sich das Token<br/>bis kurz vor Ablauf
Es gibt kein Refresh-Token und keinen Login-Bildschirm. Läuft das Token ab, holt der Dienst einfach ein neues.
Die drei Fälle bei CodamAI
Wann: Ein eigener Server deines Projekts soll eine CodamAI-API aufrufen.
-
1Client→Keycloakholt mit
client_credentialsein Token für seinen Client -
2Client→CDMSruft die API mit
Authorization: Bearer <token>auf -
3CIASprüft das Token wie jedes andere, siehe Token-Prüfung
-
4CDMSprüft die Rollen, die der Service-Account trägt
Ergebnis: Die API behandelt den Dienst wie eine Person mit dem Namen service-account-<client>.
Wann: CIAS legt Konten an, vergibt Rollen, pflegt Gruppen und Organisationen.
-
1CIAS→Keycloakmeldet sich mit dem Client
cias-adminperclient_credentialsan -
2CIASmerkt sich das Token und erneuert es 30 Sekunden vor Ablauf
-
3CIAS→Keycloakruft die Admin-API auf
Ergebnis: Der Client cias-admin kann sich nur so anmelden, ein Login im Browser ist für ihn abgeschaltet. Einstellungen unter codamai.cias.keycloak.* (client-id, client-secret).
Wann: CDMS läuft getrennt von CIAS und muss fragen, ob ein Mandant bedient wird oder welche Attributwerte eine Person im Mandanten hat.
-
1CDMS→CIAS
GET /cias/lookup/tenants/{key}oderGET /cias/lookup/users/{id}/attributes?tenantKey=…, mit einem Bearer-Token -
2CIASTrägt das Token eine der Rollen, die für den Lookup freigegeben sind?
-
3CIAS→CDMSantwortet
Ergebnis: Das Token holt sich der Dienst selbst bei Keycloak, mit Client-ID und Secret seines Clients (codamai.cias.tenancy.client.credentials), und erneuert es vor dem Ablauf. Ohne Client nimmt er ein festes Token aus codamai.cias.tenancy.client.token, das sich nicht erneuert. Welche Rollen fragen dürfen, legt lookup-roles fest; ist die Liste leer, antwortet der Endpunkt niemandem.
Eingebettet, also wenn CDMS und CIAS in einem Programm laufen, gibt es den Lookup nicht über HTTP. CDMS fragt CIAS dann direkt per Methodenaufruf. Siehe Eingebettet.
Was ein Dienst-Token darf
Ein Service-Account ist für die APIs ein Benutzer wie jeder andere, nur ohne Mensch dahinter:
| Frage | Antwort |
|---|---|
| Wer ist der Aufrufer? | der Service-Account, Name service-account-<client> |
| Welche Rollen hat er? | die Rollen, die seinem Service-Account zugeordnet sind. Keine sonst |
| In welchem Mandanten arbeitet er? | wie bei einer Person: aus dem Token. Fehlt der Mandant in MULTI, antwortet die Filterkette mit 403 |
| Was sieht er in Benutzer-Modellen? | nur Zeilen, die ihm selbst gehören |