Worum es geht
Keycloak kennt von einer Rolle nur ihren Namen. Es weiß nicht, wofür sie da ist, wer sie weitergeben darf und ob sie für die ganze Plattform oder nur in einem Mandanten gilt. Dieses Wissen führt CIAS im Rollenkatalog: eine Zeile je Rolle, mit allem, was CIAS über sie wissen muss.
Ein Katalogeintrag
GET /cias/admin/roles/tenant-user?client=cias-backend{
"client": "cias-backend", ← Client in Keycloak, leer = Realm
"key": "tenant-user", ← Name, genau wie in Keycloak
"module": "cias", ← welches Modul sie angemeldet hat
"scope": "TENANT", ← gilt in einem Mandanten
"displayName": "Tenant member", ← was Menschen lesen
"description": null, ← Erklärung für die Verwaltung
"group": "tenant", ← Anzeigegruppe in der Oberfläche
"assignableBy": ["tenant-admin", "platform-admin"],
"deprecatedAt": null ← gesetzt = stillgelegt
}| Feld | Bedeutung | Änderbar |
|---|---|---|
client + key | die Identität der Rolle, dieselben zwei Werte wie in Keycloak | nein |
module | das Modul, das die Rolle angemeldet hat. Leer bei Rollen, die niemand angemeldet hat | nein |
scope | PLATFORM oder TENANT, siehe unten | nein |
displayName, description | was Menschen lesen | ja |
group | unter welcher Überschrift eine Oberfläche die Rolle zeigt | ja |
assignableBy | wer die Rolle vergeben darf, siehe unten | ja |
deprecatedAt | seit wann das Modul die Rolle nicht mehr anmeldet | nur durch den Abgleich |
Die Identität: Client und Schlüssel
Eine Rolle ist das Paar aus Client und Schlüssel, zum Beispiel cdms-backend / model-editor. Ein Client ist in Keycloak eine Anwendung, die Tokens anfordert oder prüft. Der Schlüssel allein reicht nicht: Zwei Module dürfen beide eine Rolle model-editor haben, und das sind zwei verschiedene Rechte.
Fehlt der Client, ist es eine Realm-Rolle: eine Rolle, die in Keycloak für die ganze Plattform gilt. Davon gibt es nur wenige, siehe Die Realm-Rollen der Plattform. Was die Ebenen im Token bedeuten, steht unter Realm-Rolle, Client-Rolle, Organisationsrolle.
Der Scope: Plattform oder Mandant
Der Scope sagt, wie weit eine Vergabe reicht. Er ist eine Sicherheitsgrenze und wird beim Anlegen der Rolle festgelegt.
| PLATFORM | TENANT | |
|---|---|---|
| Reichweite | überall, folgt der Person in jeden Mandanten | nur in einem Mandanten |
| Vergabe nennt einen Mandanten | nein, verboten | ja, Pflicht |
| Wer vergibt | nur ein Plattform-Administrator | Plattform-Administrator, oder wer die Rolle delegiert bekommen hat |
| Wie in Keycloak vergeben | direkt am Konto | über die Organisation des Mandanten |
| Beispiele | platform-admin, user | tenant-admin, alle Rollen, die ein Modul anmeldet |
Mit TENANT kann dieselbe Person in einem Mandanten Administratorin sein und in einem anderen nur Leserin.
Der Scope lässt sich nicht ändern. Würde aus einer Mandantenrolle eine Plattformrolle, gälte jede schon erteilte Vergabe plötzlich überall, ohne dass an einer einzigen Vergabe etwas sichtbar wäre. Ein Versuch endet mit 400 cias.authorization.invalid-request.
Jede Rolle, die ein Modul anmeldet, bekommt den Scope TENANT. Plattformrollen kommen nur aus der Konfiguration der Installation. Warum, steht unter Module melden ihre Rollen an.
Die Delegation: wer vergeben darf
assignableBy nennt die Rollen, deren Inhaber diese Rolle vergeben dürfen. Im Beispiel oben darf jeder mit tenant-admin die Rolle tenant-user vergeben.
- Leer heißt: nur ein Plattform-Administrator. Eine leere Liste ist eine Sperre, kein Freibrief.
- Die Liste nennt nur Schlüssel, keine Clients. Die Rollen eines Aufrufers kommen im Token als flache Namensliste an, ein Client wäre dort nicht zu prüfen.
- Eine Plattformrolle wird nie delegiert, egal was in der Liste steht.
Delegation allein reicht zum Vergeben nicht. Wer vergibt, muss die Rolle auch selbst halten. Die ganze Prüfung steht unter Eine Rolle vergeben.
Stillgelegt statt gelöscht
Meldet ein Modul eine Rolle nicht mehr an, löscht CIAS sie nicht, sondern legt sie still: deprecatedAt bekommt Datum und Uhrzeit.
| aktive Rolle | stillgelegte Rolle | |
|---|---|---|
| bestehende Vergaben | gelten | gelten weiter, unverändert |
| neue Vergabe | möglich | 409 cias.authorization.role-deprecated, auch für Plattform-Administratoren |
| Entziehen | möglich | möglich |
| in der Liste „vergebbar“ | ja | nein |
| Rolle in Keycloak | vorhanden | bleibt vorhanden |
Das Datum ändert sich bei späteren Abgleichen nicht. Es sagt, wann die Rolle zurückgezogen wurde, nicht wann CIAS zuletzt gestartet ist. Meldet das Modul die Rolle wieder an, ist sie wieder aktiv, und die Vergaben waren nie weg. Mehr unter Der Abgleich mit Keycloak.
Die Endpunkte
| Aufruf | Wer | Wirkung |
|---|---|---|
GET /cias/admin/roles (?scope=…) | jede angemeldete Person | alle Rollen |
GET /cias/admin/roles/page?query=…&scope=…&page=…&size=… | jede angemeldete Person | eine Seite, mit Gesamtzahl |
GET /cias/admin/roles/assignable | jede angemeldete Person | die Rollen, die du grundsätzlich vergeben darfst |
GET /cias/admin/roles/{key}?client=… | jede angemeldete Person | ein Eintrag, sonst 404 |
POST /cias/admin/roles | Plattform-Administrator | Eintrag anlegen, 409 wenn es ihn gibt |
PUT /cias/admin/roles/{key} | Plattform-Administrator | Beschreibung, Gruppe, Delegation ändern |
DELETE /cias/admin/roles/{key}?client=… | Plattform-Administrator | Eintrag entfernen |
Einen Eintrag von Hand anzulegen, legt keine Rolle in Keycloak an. Der Katalog soll nicht durch einen Tippfehler dauerhaft eine Rolle in Keycloak erzeugen. Rollen von Modulen entstehen in Keycloak über den Abgleich. Eine von Hand angelegte Rolle gehört keinem Modul, also legt auch kein Modul sie je still.
Was der Katalog bewusst nicht kennt
- Zusammengesetzte Rollen. Keycloak kann eine Rolle aus anderen zusammensetzen. Das bleibt in Keycloak, denn was im Token landet, entscheidet ohnehin Keycloak. Eine zweite Zusammensetzung in CIAS wäre eine zweite Antwort, die verlieren würde.
- Einzelrechte. Eine Rolle trägt keine Liste, was sie darf. Das entscheidet jedes Modul selbst, in CDMS etwa je Modell und Operation.