Worum es geht
Jede Anfrage an CDMS oder CIAS läuft zuerst durch die Filterkette von CIAS. Die Filterkette ist Code, der vor jedem Endpunkt läuft. Sie beantwortet drei Fragen, bevor die eigentliche Anwendung überhaupt etwas tut:
- Wer fragt an?
- In welchem Mandanten läuft die Anfrage, und darf dieser Mandant bedient werden?
- Welche Rollen und Attribute gelten für diese Anfrage?
Das Ergebnis legt sie im RequestContext ab: einem Speicher, der genau für diese eine Anfrage gilt. CDMS liest dort nach, wer anfragt, und fragt das Token selbst nie wieder.
Die Stationen
-
FilterketteOffener Pfad?Ist der Pfad ohne Anmeldung erlaubt, etwa die öffentliche Registrierung? Dann darf auch ohne Token weiter.
-
FilterketteToken vorhanden?Steht ein Token im Header
Authorization?↳ nein 403 (bei geschützten Pfaden) -
FilterketteToken prüfenIst die Signatur mit einem Schlüssel des Realms gültig und das Token nicht abgelaufen? Stammt es vom eingestellten Issuer, ist es ein Access-Token, und ist es für diese Anwendung ausgestellt?↳ nein 401 mit
WWW-Authenticate: Bearer error="invalid_token" -
CIASToken tauschenKeycloak tauscht das Token gegen eines für den Client von CIAS↳ nein Keycloak lehnt ab: 401
cias.authentication.token-rejected. Keycloak nicht erreichbar: 503cias.authentication.identity-provider-unavailable -
CIASMandant auflösenAus welchem Mandanten kommt die Anfrage? Ist das eindeutig?↳ nein 403
cias.authentication.tenant-unresolved -
CIASMandant zulassenGibt es den Mandanten, ist er aktiv und gültig?↳ nein 403
cias.authentication.tenant-not-served -
CIASRollen und AttributeEffektive Rollen und Attribute für diesen Mandanten bilden↳ nein Attributwerte nicht abrufbar: 403
cias.authentication.tenant-not-served -
CIASWechselHeader
tenantgesetzt und durch Realm-Rolle gedeckt? Sonst still ignoriert. Danach Headeruser: Realm-Rolle da, Zielperson bekannt und im Mandanten der Anfrage, Freigabe der Zielperson da?↳ nein Benutzerwechsel: 403cias.authentication.user-switch-denied,user-switch-not-consentedoderuser-switch-unavailable -
CIASMandant Pflicht?Betriebsart MULTI, Person bekannt, aber kein Mandant?↳ nein 403
cias.authentication.tenant-required - Die Anwendung bekommt die Anfrage mit gefülltem RequestContext
Zum Schluss, nach der Antwort, räumt die Filterkette den RequestContext wieder ab. Die nächste Anfrage im selben Thread fängt leer an.
Jede Station kurz erklärt
| Station | Was passiert | Mehr dazu |
|---|---|---|
| Offener Pfad | Einige Pfade brauchen keine Anmeldung: OPTIONS-Anfragen des Browsers und, wenn eingeschaltet, /cias/registration/**. /v3/api-docs und /swagger-ui brauchen kein Token, aber Benutzer und Passwort. | Zugriff ohne Token |
| Token prüfen | Die Signatur wird gegen die öffentlichen Schlüssel des Realms geprüft, dazu Ablauf und Beginn der Gültigkeit. Außerdem: iss muss genau der eingestellte Issuer sein, typ muss Bearer sein (ein ID-Token zählt nicht), und das Token muss den Client der Anwendung in aud nennen oder von ihm selbst stammen (azp). Keycloak wird dabei nicht gefragt. | Der Identitätsanbieter: ein Issuer |
| Token tauschen | CIAS tauscht das Token bei Keycloak gegen eines für seinen eigenen Client. Erst darin stehen alle Rollen, Organisationen und Attribute. | Token-Tausch |
| Identität lesen | Aus dem getauschten Token liest CIAS Benutzer-ID, Namen, Rollen, Organisationen und Attribute. | Was aus dem Token gelesen wird |
| Mandant auflösen | aus dem Organisations-Claim (dynamisch) oder dem Attribut tenant (statisch). | Den Mandanten einer Anfrage bestimmen |
| Mandant zulassen | Das Mandanten-Tor fragt, ob der Mandant bedient wird. Die Antwort wird 30 Sekunden gemerkt. | Den Mandanten zulassen |
| Rollen und Attribute | Globale Rollen oder Rollen im Mandanten, Attributwerte pro Mandant. | Effektive Rollen |
| Wechsel | Erst der Mandantenwechsel, dann der Benutzerwechsel per Header, jeder nur mit seiner Realm-Rolle. Ein Benutzerwechsel ohne Rolle, zu einer unbekannten Person oder zu einer Person außerhalb des Mandanten wird abgelehnt. | Mandantenwechsel per Header, Benutzerwechsel per Header |
Der Ablauf als Sequenz
sequenceDiagram
participant C as Client
participant S as Filterkette
participant K as Keycloak
participant T as Mandanten-Tor
participant A as CDMS
C->>S: Anfrage mit Bearer-Token
S->>S: Signatur, Ablauf, Issuer, Typ, Audience prüfen
S->>K: Token tauschen (oder aus dem Cache)
K-->>S: Token für den CIAS-Client
S->>S: Identität lesen, Mandant auflösen
S->>T: wird Mandant acme bedient?
T-->>S: ja (30 s gemerkt)
S->>S: Rollen, Attribute, Wechsel
S->>A: Anfrage mit RequestContext
A-->>C: Antwort
S->>S: RequestContext abräumen
Die Ausgänge
Wann: Token echt, nicht abgelaufen, Mandant eindeutig und bedient.
Der RequestContext enthält Benutzer-ID, Namen, Mandant, erlaubte Mandanten, Realm-Rollen, Fachrollen, Gruppen und Attribute. Die Anwendung prüft danach ihre eigenen Rollen.
Ergebnis: Die Anfrage erreicht die Anwendung.
Wann: Kein Header Authorization, oder ohne das Wort Bearer.
Offene Pfade gehen durch. Jeder andere Pfad bekommt 403, ohne CDMS-Fehlerkörper.
Ergebnis: Erst anmelden. Siehe Zugriff ohne Token.
Wann: Abgelaufen, kaputt, mit einem fremden Schlüssel signiert, von einem anderen Issuer, ein ID-Token oder für einen anderen Client ausgestellt.
Die Prüfung scheitert, bevor CIAS das Token überhaupt liest. Antwort 401 cias.authentication.token-rejected mit WWW-Authenticate: Bearer error="invalid_token". Das gilt auch auf offenen Pfaden: Ein kaputtes Token wird nicht wie „kein Token“ behandelt.
Ergebnis: Token erneuern und die Anfrage wiederholen. Siehe Token erneuern.
Wann: Keycloak lehnt den Token-Tausch ab oder liefert kein Token.
CIAS schreibt den Grund ins Log und beendet die Anfrage mit 401 cias.authentication.token-rejected. Eine Anfrage läuft nie ohne Identität weiter.
Ergebnis: Siehe Token-Tausch.
Wann: Keycloak antwortet beim Token-Tausch nicht oder mit einem Serverfehler (5xx).
503 cias.authentication.identity-provider-unavailable. Am Token liegt es nicht; dieselbe Anfrage kann später gelingen.
Ergebnis: Später wiederholen. Der Betrieb sieht den Grund im Log.
Wann: Betriebsart MULTI, die Person ist bekannt, aber aus dem Token ergibt sich kein Mandant.
Die Filterkette lehnt mit 403 cias.authentication.tenant-required ab. Ausgenommen sind die Pfade von CIAS selbst unter /cias/**, damit die Person zumindest ihre eigene Profilseite öffnen kann.
Ergebnis: Der Person fehlt eine Organisation oder das Attribut tenant.
Wann: Die Person gehört mehreren Organisationen an, und nichts sagt, welche gemeint ist. Oder das Attribut tenant nennt eine Organisation, in der sie nicht Mitglied ist.
403 cias.authentication.tenant-unresolved.
Ergebnis: Der Client wählt den Mandanten mit dem Header tenant, siehe Den Mandanten einer Anfrage bestimmen.
Wann: Der Mandant ist unbekannt, gesperrt, geschlossen, außerhalb seiner Gültigkeit, oder CIAS ist nicht erreichbar und nichts ist gemerkt.
403 cias.authentication.tenant-not-served. Alle Gründe bekommen absichtlich denselben Schlüssel, damit niemand über die Antwort herausfinden kann, welche Kunden es gibt. Das Log unterscheidet sie.
Ergebnis: Siehe Den Mandanten zulassen (Mandanten-Tor).
Wann: Die Anfrage trägt den Header user, aber die Realm-Rolle allowed-user-context-switch fehlt, die Zielperson ist unbekannt oder gehört nicht zum Mandanten, oder user-roles hat einen ungültigen Wert.
403 cias.authentication.user-switch-denied. Hat die Zielperson den Wechsel nicht freigegeben, 403 cias.authentication.user-switch-not-consented. Kann CIAS gar nicht nachschlagen, wer die Zielperson ist, oder die Freigabe nicht prüfen, 403 cias.authentication.user-switch-unavailable. Der genaue Grund steht nur im Log.
Ergebnis: Siehe Benutzerwechsel per Header.
Wann: Betriebsart SINGLE: Es gibt keine Mandanten.
Mandant auflösen und Mandanten-Tor entfallen. Ein Mandant im Token wird ignoriert, die Liste der erlaubten Mandanten ist leer, der Header tenant bewirkt nichts. Rollen im Mandanten gelten nicht, nur Realm-Rollen und die globalen Client-Rollen.
Ergebnis: Siehe In SINGLE zählt der Mandant im Token nicht.
Der Identitätsanbieter: ein Issuer
Woran „der eingestellte Issuer“ gemessen wird, steht an genau einer Stelle: CIAS_ISSUER, der Issuer so, wie er im Token steht, zum Beispiel https://sso.example.com/realms/example. Daraus leitet CIAS den Realm, die Adresse der Schlüssel und die des Token-Tauschs ab. Erreicht der Dienst Keycloak über eine andere Adresse als der Browser, etwa im Container-Netz, nennt CIAS_BACKCHANNEL_URL diese Adresse. Der Issuer bleibt derselbe.
Die Fehlerantwort der Filterkette
Lehnt die Filterkette ab, sieht die Antwort immer so aus, mit dem passenden Status:
GET /api/rest/crm/customer/read/42
Authorization: Bearer eyJ…403
{ "error": "cias.authentication.tenant-not-served", "message": "request refused" }Schlüssel in error | Bedeutung |
|---|---|
cias.authentication.token-rejected | 401: Token ungültig, fremd oder vom Token-Tausch abgelehnt |
cias.authentication.identity-provider-unavailable | 503: Keycloak gerade nicht erreichbar |
cias.authentication.tenant-unresolved | Mandant nicht eindeutig oder widersprüchlich |
cias.authentication.tenant-not-served | Mandant wird nicht bedient, oder seine Daten sind gerade nicht abrufbar |
cias.authentication.tenant-required | Betriebsart MULTI, aber kein Mandant |
cias.authentication.user-switch-denied | Benutzerwechsel nicht erlaubt: Rolle fehlt, Zielperson unbekannt oder nicht im Mandanten, ungültiges user-roles |
cias.authentication.user-switch-not-consented | Benutzerwechsel nicht freigegeben: die Zielperson hat diesem Wechsel nicht zugestimmt, oder die Freigabe ist abgelaufen oder widerrufen |
cias.authentication.user-switch-unavailable | Benutzerwechsel nicht möglich: CIAS kann die Zielperson oder ihre Freigabe gerade nicht prüfen |
Das Format ist ein anderes als bei CDMS-Fehlern (messageKey). Ein 403 mit error kommt aus der Filterkette, ein 403 mit messageKey aus CDMS. Siehe 401, 403, 404.