Worum es geht
Ein Token ist ein JSON-Dokument mit Claims: benannten Angaben wie sub (wer), exp (bis wann) oder realm_access (welche Rollen). CIAS liest die Claims aus dem getauschten Token und legt die Ergebnisse in den RequestContext. Von dort liest CDMS, und nur von dort.
Vom Token zum RequestContext
flowchart LR
subgraph T["Getauschtes Token"]
sub["sub"]
name["name / preferred_username"]
rr["realm_access.roles"]
cr["resource_access.(client).roles"]
grp["groups"]
org["organization"]
ten["tenant"]
at["allowedTenants"]
oth["projects, …"]
end
subgraph R["RequestContext"]
uid["userId"]
un["userName"]
err["effectiveUserRealmRoles"]
eur["effectiveUserRoles"]
eug["effectiveUserGroups"]
ut["userTenant"]
alt["allowedTenants"]
eua["effectiveUserAttributes"]
end
sub --> uid
name --> un
rr --> err
cr --> eur
org -. "Rollen im Mandanten ersetzen" .-> eur
grp --> eug
org --> ut
ten --> ut
at --> alt
org --> alt
oth --> eua
Die Tabelle
| Claim im Token | Einstellung | Landet in | Hinweis |
|---|---|---|---|
sub | claims.user-id | userId | die ID des Kontos in Keycloak |
name, sonst preferred_username | claims.user-name | userName | der erste, der einen Wert hat |
realm_access.roles | claims.realm-roles | effectiveUserRealmRoles | gelten immer, in jedem Mandanten |
resource_access.<client>.roles | claims.client-roles | effectiveUserRoles | nur der eigene Client. Rollen im Mandanten können sie ersetzen |
groups | claims.groups | effectiveUserGroups | die Gruppen, so wie Keycloak sie ins Token schreibt |
organization | organization.claim | userTenant, allowedTenants, Rollen im Mandanten | der Alias einer Organisation ist der Mandantenschlüssel |
tenant | claims.tenant-attribute | userTenant | der statische Weg zum Mandanten, erster Wert |
allowedTenants | claims.allowed-tenants-attribute | allowedTenants | Liste, an Kommas getrennt |
| alle übrigen | – | effectiveUserAttributes | als Liste von Texten |
Alle Einstellungen liegen unter codamai.cias.token. Wer einen Claim umbenennt, stellt hier den neuen Namen ein.
Jede Ausprägung
Wann: bei jedem Token mit Person
sub wird zur userId. Sie ist das, was CDMS in _userId und in der Historie speichert. Der Name kommt aus name oder, wenn der fehlt, aus preferred_username. Ein Service-Account hat keinen name und heißt deshalb service-account-<client>.
Wann: bei jedem Token
Realm-Rollen aus realm_access.roles gehen unverändert nach effectiveUserRealmRoles. Fachrollen kommen aus resource_access.<client>.roles, und zwar nur für den eigenen Client von CIAS. Die Rollen anderer Clients im Token werden nicht gelesen.
Ergebnis: Wie Rollen im Mandanten die Fachrollen ersetzen: Effektive Rollen.
Wann: wenn Keycloak Gruppen ins Token schreibt
Der Claim groups wird zu effectiveUserGroups. Die Rollen aus Gruppen stehen ohnehin schon an ihren Plätzen im Token; die Gruppen selbst sind nur zur Information da.
Wann: bei dynamischen Mandanten
Der Claim organization sagt, in welchen Organisationen die Person Mitglied ist und welche Rollen sie dort hat. CIAS versteht drei Formen: eine Liste von Aliasen, ein Objekt mit dem Alias als Schlüssel oder eine Liste von Objekten mit dem Alias unter alias oder name. Einträge ohne Alias werden verworfen. Der Alias ist der Mandantenschlüssel.
Ergebnis: Welcher Mandant daraus wird: Den Mandanten einer Anfrage bestimmen.
Wann: in der Betriebsart MULTI
allowedTenants im RequestContext ist eine Liste in fester Reihenfolge: zuerst der eigene Mandant, dann alle Organisationen der Person, dann die Werte des Attributs allowedTenants, an Kommas getrennt. In SINGLE ist die Liste leer.
Ergebnis: Die Liste entscheidet über den Mandantenwechsel per Header.
Wann: für jeden übrigen Claim
Jeder Claim, der nicht in der Tabelle oben steht und kein Protokoll-Claim ist, wird zum Attribut, etwa projects. Der Wert wird immer zu einer Liste von Texten: Ein einzelner Wert wird zur Liste mit einem Eintrag. Objekte und verschachtelte Listen werden übersprungen. Ist ein Attribut pro Mandant angemeldet, ersetzt der Wert aus CIAS den aus dem Token.
Ergebnis: Wofür CDMS die Attribute nutzt: Attributfilter.
Wann: Claims, die zum Protokoll gehören
Diese Claims werden nicht zu Attributen: iss, sub, aud, exp, nbf, iat, jti, typ, azp, nonce, auth_time, acr, amr, sid, session_state, scope, client_id und ähnliche, die Profil-Claims wie name, email, preferred_username, locale, dazu realm_access, resource_access, allowed-origins, groups und organization.
Ergebnis: Eine E-Mail-Adresse im Token ist also kein Attribut für einen Filter.
Ein Beispiel
{
"sub": "7f3c…",
"preferred_username": "anna",
"name": "Anna Berg",
"realm_access": { "roles": ["offline_access"] },
"resource_access": { "cdms-backend": { "roles": ["hr-employee-read"] } },
"organization": { "nordbau": { "id": "a1b2…" } },
"projects": ["alpha", "beta"],
"email": "anna@nordbau.example"
}userId = 7f3c…
userName = Anna Berg
userTenant = nordbau
allowedTenants = [nordbau]
effectiveUserRealmRoles = [offline_access]
effectiveUserRoles = [hr-employee-read]
effectiveUserAttributes = { projects: [alpha, beta] }email ist ein Protokoll-Claim und wird kein Attribut. projects schon.