Worum es geht
Ein Modul meldet seine Attribute in derselben Deklaration an wie seine Rollen, siehe Module melden ihre Rollen an. Eine Deklaration ist die Liste, mit der ein Modul sagt: „Das brauche ich.“ CIAS liest sie beim Abgleich und macht daraus drei Dinge:
- einen Eintrag im Benutzerprofil von Keycloak, damit ein Konto den Wert überhaupt speichern kann,
- einen Claim-Mapper am Client des Moduls, damit der Wert im Token ankommt,
- einen Eintrag im Attributkatalog von CIAS, der festhält, wer das Attribut angemeldet hat und wer es schreiben darf.
Was eine Anmeldung enthält
Jedes Attribut hat sechs Teile:
| Teil | Bedeutung | fehlt es … |
|---|---|---|
key | der Name, genau so im Profil und im Token | Pflicht |
multivalued | eine Liste statt eines Werts. Ein Attributfilter braucht fast immer eine Liste | ein Wert |
defaultValue | was Konten bekommen, die älter sind als das Attribut | kein Standardwert |
required | das Modul kann ohne den Wert nicht arbeiten | optional |
selfEditable | die Person darf den Wert selbst ändern | nur Administratoren |
binding | USER: ein Wert pro Person. USER_IN_TENANT: ein Wert je Person und Mandant | USER |
In Java schreibt ein Modul das mit kurzen Bausteinen:
Attribute.optional("region").asMultivalued() // optional, Liste
Attribute.required("customerId", "unbekannt") // Pflicht, mit Standardwert
Attribute.preference("locale", "de") // die Person ändert es selbst
Attribute.optional("areas").asMultivalued().perTenant() // eine Liste je MandantEin getrennt laufendes Modul liefert dieselbe Liste als JSON unter GET /cias/fetch:
GET /cias/fetch{
"roles": [ … ],
"attributes": [
{ "key": "region", "multivalued": true, "defaultValue": null,
"required": false, "selfEditable": false, "binding": "USER" }
]
}Das Feld binding kommt dabei genauso an wie im eingebetteten Betrieb. Fehlt es, gilt USER, so wie bei einem Modul, das älter ist als das Feld. Einen Wert, den CIAS nicht kennt, rät es nicht: Die Anmeldung dieses Moduls gilt dann wie ein nicht erreichbares Modul, und beim Abgleich bleibt alles, wie es war.
Formatregeln wie eine Länge oder ein Muster kann eine Anmeldung nicht enthalten. Ob eine neue Regel sicher ist, hängt von den Werten ab, die schon in den Konten stehen, und die kennt das Modul nicht. Solche Regeln pflegt, wer den Realm betreibt, von Hand im Benutzerprofil. CIAS lässt sie dort stehen.
Die Ausprägungen
Wann: required ist false. So meldet CDMS jedes Attribut aus dem Modell an.
Das Konto darf ohne Wert sein. Was das Modul dann tut, entscheidet das Modul. Ein Attributfilter in CDMS lehnt die Anfrage ab, wenn der Wert fehlt.
Ergebnis: angenommen
Wann: required ist true, defaultValue ist gesetzt.
Keycloak füllt den Standardwert bei allen Konten ein, die ihn noch nicht haben. Pflicht ist der Wert für eine Person, die ein Formular ausfüllt, nie für CIAS, das über die Verwaltungs-API schreibt.
Ergebnis: angenommen
Wann: required ist true, defaultValue fehlt oder ist leer.
Alle Konten, die älter sind als das Attribut, hätten keinen Wert. Keycloak lehnt dann jede Änderung an so einem Konto ab, auch das Sperren. Das Recht zu entziehen wäre das Erste, was kaputtgeht.
Ergebnis: abgewiesen: die ganze Deklaration dieses Moduls, auch seine Rollen, Status REJECTED
Wann: selfEditable ist true, etwa bei locale.
Die Person darf den Wert selbst ändern, auch auf Keycloaks eigener Kontoseite. Administratoren dürfen es weiterhin.
Ergebnis: angenommen
Wann: binding ist USER_IN_TENANT.
Die Person kann in jedem Mandanten einen anderen Wert haben. Die Werte führt CIAS, nicht Keycloak. Siehe Ein Wert pro Person oder pro Mandant.
Ergebnis: angenommen
Wann CIAS eine Anmeldung abweist
| Befund | betrifft | Folge |
|---|---|---|
| Pflichtattribut ohne Standardwert | ein Modul | REJECTED: die ganze Deklaration des Moduls fällt aus diesem Lauf |
| dasselbe Attribut zweimal verschieden im selben Modul | ein Modul | REJECTED |
| der Katalog führt das Attribut für ein anderes Modul, und dieses Modul beschreibt es anders | ein Modul | REJECTED |
| zwei Module beschreiben dasselbe Attribut im selben Lauf verschieden | alles | SKIPPED: der Lauf schreibt nichts, für kein Modul |
| zwei Module beschreiben dasselbe Attribut gleich | – | kein Widerspruch, beide dürfen es anmelden |
Warum so streng? Das Benutzerprofil ist ein Dokument für den ganzen Realm. Zwei verschiedene Beschreibungen desselben Attributs beschreiben dasselbe Feld, und wer zuletzt schriebe, gewönne. Das merkte niemand, bis ein Filter falsche Zeilen liefert.
Was in Keycloak entsteht
-
1CIAS→Keycloakträgt
regionins Benutzerprofil ein: mehrwertig, sehen dürfen Administrator und Person, ändern nur Administratoren, kein Standardwert, nicht Pflicht -
2CIAS→Keycloaklegt am Client des Moduls einen Claim-Mapper
regionan: Wert des Attributs → Claimregionin Access-Token, ID-Token und UserInfo, als Liste -
3CIASlegt im Katalog den Eintrag
regionan, EigentümercdmsErgebnis: Ab jetzt kann ein Kontoregiontragen, und das Token des Clients bringt es mit
Das Profil schreibt CIAS einmal pro Lauf für alle Module zusammen, denn Keycloak ersetzt es bei jedem Schreiben ganz. Was CIAS nicht angemeldet hat, bleibt darin stehen, auch Regeln und Anzeigenamen, die jemand von Hand gepflegt hat. Ändert ein Modul seine Anmeldung, etwa von einem Wert auf eine Liste, passt der nächste Abgleich Profil und Mapper an.
Der Attributkatalog
Den Katalog liest jede angemeldete Person:
GET /cias/admin/attributes/regionHTTP 200
{
"key": "region",
"module": "cdms",
"displayName": "region",
"description": null,
"group": null,
"multivalued": true,
"required": false,
"defaultValue": null,
"selfEditable": false,
"binding": "USER",
"assignableBy": [],
"deprecatedAt": null
}| Feld | Bedeutung |
|---|---|
module | wer das Attribut angemeldet hat. Solange es angemeldet ist, kann kein anderes Modul es anders beschreiben |
displayName, description, group | für Verwaltungsseiten. Die Anmeldung nennt sie nicht; der Name ist daher der Schlüssel |
assignableBy | welche Rollen den Wert je Mandant schreiben dürfen. Leer heißt: nur Plattform-Administratoren. Siehe Wer ein Attribut schreiben darf |
deprecatedAt | gesetzt, wenn kein Modul das Attribut mehr anmeldet. Siehe Wie ein Attribut wieder verschwindet |
Der Katalog ist nur lesbar. Einträge entstehen allein durch den Abgleich: Ein Attribut gibt es, weil ein Modul es braucht. GET /cias/admin/attributes liefert alle Einträge, ohne Anmeldung gibt es 403, für einen unbekannten Schlüssel 404.