Anmeldestufe und Step-up

Worum es geht

Für die meisten Operationen reicht es, dass jemand angemeldet ist. Manche verlangen mehr: Wer eine Vorlage freigibt oder Rollen vergibt, soll sich vielleicht mit einem zweiten Faktor angemeldet haben, oder vor kurzem. Ein zweiter Faktor ist etwas neben dem Passwort, etwa ein Code aus einer Authenticator-App oder ein Sicherheitsschlüssel.

Dafür gibt es zwei Angaben:

• Die Anmeldestufe sagt, wie stark sich jemand angemeldet hat.
• Das Höchstalter der Anmeldung sagt, wie lange die Anmeldung höchstens her sein darf.

Reicht die Anmeldung für eine Operation nicht, antwortet das Backend mit 401 und sagt genau, was fehlt. Die Oberfläche schickt die Person dann noch einmal zu Keycloak, und Keycloak fragt nur nach dem Schritt, der fehlt. Das heißt Step-up: die Anmeldung um eine Stufe anheben, ohne von vorn anzufangen.

Die drei Stufen

Phishing-resistent heißt: Eine nachgebaute Seite unter einer fremden Adresse kann mit diesem Faktor nichts anfangen. Der Schlüssel antwortet nur der echten Adresse.

Die Stufen sind geordnet. Eine stärkere Anmeldung erfüllt jede schwächere Anforderung: Wer sich phishing-resistant angemeldet hat, erfüllt auch mfa und basic.

Die drei Stufen sind fest. Eine Installation kann keine eigene Stufe hinzufügen und keine umbenennen. Ein Modul schreibt in seinem Code einmal „das braucht mfa“, und das soll in jeder Installation dasselbe heißen. Die Namen beschreiben, was die Person getan hat, nicht wie ein Identity Provider es zählt. So bleiben sie auch gültig, wenn der Identity Provider wechselt.

Das Höchstalter

Eine Anforderung besteht aus einer Stufe und, wenn gewünscht, einem Höchstalter. Das Höchstalter ist eine ganze Zahl von Sekunden, mindestens eine. Genauer lässt es sich einer Oberfläche nicht mitteilen.

Die Zeit der Anmeldung steht im Token im Claim auth_time. Ein Claim ist eine benannte Angabe im Token. Eine Anforderung ist erfüllt, wenn

• die Stufe der Person die verlangte Stufe erfüllt und
• bei gesetztem Höchstalter die Anmeldung nicht länger her ist als das Höchstalter. Genau das Höchstalter zählt noch.

Ein paar Beispiele:

Fehlt die Anmeldezeit, erfüllt das kein Höchstalter. Einen Spielraum für abweichende Uhren gibt es nicht. Wird jemand knapp abgewiesen, meldet er sich neu an, bekommt eine frische Anmeldezeit und kommt durch.

Woher die Stufe kommt

Keycloak nennt das Konzept Level of Authentication. Die Stufe steht im Token im Claim acr. Damit dort CIAS’ eigene Namen stehen und keine Zahlen, bringt CIAS sie Keycloak bei:

• CIAS schreibt seine drei Namen in die Zuordnung von ACR zu LoA des Realms, das Attribut acr.loa.map: basic 1, mfa 2, phishing-resistant 3. Das passiert bei jedem Abgleich. Namen, die ein Betreiber selbst eingetragen hat, bleiben stehen.
• Keycloak schreibt danach genau diese Namen in acr: nach einer frischen Anmeldung basic, nach einem Step-up auf mfa dann mfa. Ein Token-Refresh behält die Stufe.
• Welche Faktoren Keycloak abfragt, legt der Betreiber im Browser Flow des Realms fest. Das ist der Anmeldeablauf, den Keycloak beim Login abarbeitet. Für jede Stufe über basic braucht er einen Schritt mit der Bedingung „Condition – Level of Authentication“ und der Nummer der Stufe. CIAS baut und ändert diesen Ablauf nie. Es liest nur, welche Stufen er erreichen kann.

Die Oberfläche fragt eine Stufe beim Login mit acr_values an. Verlangt das Backend ein Höchstalter, schickt sie zusätzlich prompt=login: Keycloak meldet dann in jedem Fall neu an, und die Anmeldezeit ist frisch. Fehlt im Browser Flow der Schritt für eine Stufe, ignoriert Keycloak acr_values still und stellt ein Token mit der Stufe aus, die der Ablauf hat. Das Backend lehnt dann wieder ab. Damit das nicht erst einer Person auffällt, vergleicht der Abgleich die verlangten Stufen mit den erreichbaren und meldet jede, die fehlt. Siehe Der Abgleich mit Keycloak und Der Keycloak-Adapter.

Im Zweifel basic

CIAS liest die Stufe so, dass ein Fehler nie mehr Rechte gibt. Das heißt Fail-closed, siehe Im Zweifel ablehnen.

Keycloak schreibt zum Beispiel 0 in acr, wenn eine Sitzung nur aus einem Cookie wiederhergestellt wurde. Auch das liest CIAS als basic.

Das vorgelegte Token zählt

Bei jeder Anfrage tauscht CIAS das Token gegen eines für das Backend. Stufe und Anmeldezeit liest CIAS aber aus dem Token, das der Aufrufer vorgelegt hat, also vor dem Tausch.

Der Grund: Das vorgelegte Token ist das, für das sich die Person angemeldet hat. Sein acr ist das Ergebnis des Anmeldeablaufs, den die Oberfläche angefragt hat. Der Token-Tausch von Keycloak behält die Stufe nicht: Das getauschte Token einer Person, die sich gerade auf mfa angehoben hat, trägt wieder basic. Läse CIAS das getauschte Token, ginge jeder Step-up auf dem Weg ins Backend verloren.

Im RequestContext stehen beide Werte als authenticationLevel und authenticatedAt. Der RequestContext ist der Speicher für die Angaben einer Anfrage, aus dem CDMS und die anderen Module lesen.

Benutzerwechsel

Beim Benutzerwechsel arbeitet eine berechtigte Person im Namen einer anderen. Stufe und Anmeldezeit wechseln dabei nicht mit. Sie beschreiben die Person an der Tastatur, nicht die Person, als die gearbeitet wird.

Ein Administrator, der in eine Person wechselt, die sich gerade mit zweitem Faktor angemeldet hat, erbt diese Anmeldung also nicht. Verlangt eine Operation mfa, muss er sich mit zweitem Faktor angemeldet haben.

Service-Accounts

Ein Service-Account ist das Konto, mit dem sich ein Dienst selbst anmeldet, ohne Person, siehe Anmelden als Dienst. CIAS erkennt sein Token an azp (dem Client, für den das Token ausgestellt ist) und preferred_username in der Form service-account-<client>, beides aus dem vorgelegten Token.

Ein Service-Account hat immer die Stufe basic und keine Anmeldezeit, denn sein Token enthält beides nicht. Er kann sich auch nicht neu anmelden. Eine Anforderung über basic oder mit Höchstalter könnte er nie erfüllen.

Ob ein Service-Account von einer Anforderung ausgenommen ist, entscheidet jedes Modul selbst:

Die Antwort, wenn die Anmeldung nicht reicht

sequenceDiagram
    participant O as Oberfläche (BFF)
    participant B as Backend
    participant K as Keycloak
    O->>B: Anfrage mit Token (acr = basic)
    B->>B: Recht vorhanden? ja
    B->>B: Anmeldung reicht? nein, verlangt ist mfa
    B-->>O: 401, step-up-required, acr_values="mfa"
    O->>K: Login mit acr_values=mfa
    K-->>O: fragt nur den zweiten Faktor ab, neues Token (acr = mfa)
    O->>B: dieselbe Anfrage noch einmal
    B-->>O: 200

Das Backend ist hier CDMS, CRMS oder CIAS selbst. Wie die Oberflächen darauf reagieren, mit Dialog, Fenster und genau einer Wiederholung, steht unter Eine stärkere Anmeldung nachholen (Step-up).

Die Antwort hat zwei Teile: einen Kopf nach dem Standard RFC 9470, den jeder Client verstehen kann, und einen Körper im Fehlerformat der Plattform, den die Oberflächen übersetzen.

POST /cias/admin/role-assignments
Authorization: Bearer eyJ…   (acr = basic)

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication", error_description="A stronger or more recent sign-in is required", acr_values="mfa", max_age=300

{ "messageKey": "cias.authentication.step-up-required|mfa|300", "code": "401", "layer": "api" }

Der Schlüssel trägt seine Angaben nach |:

cias.authentication.step-up-required|<stufe>
cias.authentication.step-up-required|<stufe>|<sekunden>

• Die erste Angabe ist die verlangte Stufe.
• Die zweite ist das Höchstalter in Sekunden. Ohne Höchstalter fehlt sie, und im Kopf fehlt max_age.

Kopf und Körper sagen immer dasselbe, denn CIAS liest den Kopf aus dem Schlüssel, den das Modul geschrieben hat. Kein Modul schreibt den Kopf selbst. So steht im Kopf genau die Anforderung, die geprüft wurde.

Zwei Arten von 401

Am Wert von error im Kopf erkennt ein Client, welche der beiden Antworten er vor sich hat.

Erst das Recht, dann die Anmeldung

Jedes Modul prüft zuerst, ob die Person die Operation überhaupt darf. Erst danach prüft es, ob die Anmeldung reicht.

Andersherum würde CIAS eine Person zu einer stärkeren Anmeldung schicken, die sie danach trotzdem nicht hineinlässt.

Anforderungen stehen fest

Wo eine Anforderung gilt, sagt das Modul an der Stelle, an der es fachlich entscheidet, nie je URL:

• CDMS je Modell und Operation, siehe Anmeldestufe je Modell und Operation.
• CRMS je Stufe einer Freigabe und für das Lesen und Ändern endgültiger Dokumente, je Art des Dokuments.
• CIAS selbst je Bereich seiner Verwaltung, siehe Anmeldestufe für die Verwaltung.

Jedes Modul meldet die Stufen, die es verlangt, in seiner Deklaration an. So kann der Abgleich prüfen, ob Keycloak sie erreicht.

Wo eine Installation eine Anforderung einstellt, steht der Wert beim Bauen oder Ausrollen fest: als Einstellung, die eine Umgebungsvariable überschreiben kann. Zur Laufzeit lässt sich keine Anforderung ändern, weder über einen Endpunkt noch über eine Oberfläche. Wer eine Anforderung senken könnte, könnte den Step-up abschalten.

Fallen

Weiter

• Eine stärkere Anmeldung nachholen (Step-up)
• Anmeldestufe für die Verwaltung
• Was aus dem Token gelesen wird
• Token-Tausch (Token-Exchange)
• Der Abgleich mit Keycloak