CodamAIDocs
Themafertig

Eine stärkere Anmeldung nachholen (Step-up)

Was passiert, wenn eine Aktion eine stärkere oder frischere Anmeldung verlangt: von der Ablehnung im Modul über die neue Anmeldung bei Keycloak bis zur wiederholten Anfrage.

Ausprägungen
Anmeldestufe fehltAnmeldung zu altAnmeldestufe nicht erreichbarRecht fehltDienstkontoSeite wird auf dem Server geladen

Worum es geht

Für die meisten Aktionen reicht es, angemeldet zu sein. Manche verlangen mehr: Gehaltsdaten liest nur, wer sich mit einem zweiten Faktor angemeldet hat (etwa einem Code aus einer App), und eine Vorlage gibt nur frei, wer sich gerade eben angemeldet hat.

Ein Step-up ist das Nachholen genau dieses Mehr: Die Person meldet sich erneut an, Keycloak fragt nur den fehlenden Schritt, und das Portal wiederholt die Aktion. Die Person muss sich dafür nicht abmelden und verliert nichts von dem, was sie gerade sieht.

Zwei Wörter vorweg:

  • Die Anmeldestufe sagt, wie stark sich jemand angemeldet hat. Es gibt genau drei, aufsteigend: basic (angemeldet, egal wie), mfa (mit zweitem Faktor) und phishing-resistant (mit einem Faktor, der an die Adresse gebunden ist, etwa einem Passkey). Eine höhere Stufe erfüllt immer auch eine niedrigere.
  • Das Höchstalter der Anmeldung sagt, wie lange die Anmeldung höchstens her sein darf, in ganzen Sekunden.

Eine Anforderung ist immer eine Stufe und, wenn nötig, ein Höchstalter. Mehr dazu unter Die Anmeldestufe.

Ein Beispiel, Ende zu Ende

Im Modell salary (Gehälter) steht: Lesen verlangt die Stufe mfa. Eine Person mit der Leserolle hat sich am Morgen nur mit Passwort angemeldet und öffnet jetzt die Liste der Gehälter.

sequenceDiagram
    participant B as Browser
    participant P as Anmeldefenster
    participant BFF as BFF
    participant F as Filterkette (CIAS)
    participant D as CDMS
    participant K as Keycloak
    B->>BFF: Liste „Gehälter“ öffnen
    BFF->>F: POST /api/rest/hr/salary/query mit Token
    F->>F: liest Stufe basic und Anmeldezeit aus dem Token
    F->>D: Anfrage mit RequestContext
    D->>D: Rolle für Lesen da? ja. Stufe mfa erreicht? nein
    D-->>BFF: 401 step-up-required|mfa
    BFF-->>B: 401, Schlüssel unverändert
    B->>B: Dialog: „Diese Aktion verlangt eine Anmeldung mit zweitem Faktor.“
    B->>P: Klick auf „Neu anmelden“ öffnet das Fenster
    P->>K: Anmeldung mit acr_values=mfa
    K->>P: fragt nur den zweiten Faktor
    K-->>BFF: neue Tokens mit acr=mfa ins Sitzungs-Cookie
    P-->>B: meldet „fertig“ und schließt sich
    B->>BFF: dieselbe Anfrage noch einmal
    BFF->>F: POST /api/rest/hr/salary/query mit neuem Token
    F->>D: Stufe mfa
    D-->>B: 200, die Gehälter

Dieselben Schritte in Worten:

Ein Step-up für eine Leseanfrage
  1. 1
    BFF→CDMS
    schickt POST /api/rest/hr/salary/query mit dem Access-Token der Person
  2. 2
    Filterkette
    liest die Anmeldestufe aus dem Claim acr und den Zeitpunkt der Anmeldung aus auth_time
    Beide kommen aus dem Token, das der BFF mitgeschickt hat, nicht aus dem getauschten. Fehlt acr oder steht dort ein unbekannter Wert, gilt basic. Beides landet im RequestContext.
  3. 3
    CDMS
    prüft zuerst die Rolle für das Lesen, dann die Anmeldung
    Die Rolle ist da. Die Stufe basic erfüllt mfa nicht.
  4. 4
    CDMS→BFF
    antwortet 401 mit dem Schlüssel cias.authentication.step-up-required|mfa
    Dazu kommt der Standard-Header WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="mfa". Bei einer Suche antwortet die ganze Anfrage mit 401. Es werden keine Zeilen still herausgefiltert.
  5. 5
    BFF→Browser
    reicht die 401 mit dem Schlüssel unverändert als messageKey weiter
  6. 6
    Frontend
    erkennt den Schlüssel und zeigt einen Dialog: „Diese Aktion verlangt eine Anmeldung mit zweitem Faktor.“
    Verlangt die Aktion auch ein Höchstalter, steht dort zusätzlich etwa „Sie darf nicht älter als 5 min sein.“ Scheitern mehrere Anfragen gleichzeitig, gibt es nur einen Dialog und eine Anmeldung.
  7. 7
    Benutzer
    klickt auf „Neu anmelden“
    Das öffnet ein kleines Anmeldefenster (Popup). Ein Klick ist nötig, weil Browser ein Popup ohne Klick blockieren. Ist es trotzdem blockiert, sagt der Dialog das und bittet, Popups zu erlauben.
  8. 8
    Frontend→Keycloak
    meldet die Person im Fenster neu an, mit acr_values=mfa
  9. 9
    Keycloak
    kennt die Sitzung schon und fragt nur den fehlenden Schritt, hier den zweiten Faktor
    Das neue Token trägt acr=mfa. Der BFF legt es wie jedes Token in sein Sitzungs-Cookie.
  10. 10
    Frontend
    Das Fenster meldet „fertig“ an das Portal und schließt sich
    Es meldet sich über einen Kanal im Browser (BroadcastChannel codamai.step-up), der nur zwischen Seiten derselben Adresse funktioniert.
  11. 11
    BFF→CDMS
    dieselbe Anfrage noch einmal, jetzt mit dem neuen Token
  12. 12
    CDMS→Browser
    liefert die Liste
    Ergebnis: Die Person sieht die Gehälter. Die Anfrage wurde genau einmal wiederholt.

Das gilt für jede Anfrage eines Portals, nicht nur für dieses Beispiel. Die Portale behandeln einen Step-up an einer einzigen Stelle, durch die alle ihre Anfragen laufen. Keine einzelne Seite muss davon wissen.

Die Ausprägungen

Wie ein Step-up ausgehen kann

Wann: Die Aktion verlangt mfa oder phishing-resistant, die Person hat sich schwächer angemeldet.

Der Ablauf aus dem Beispiel. Das Portal schickt die Stufe als acr_values. Keycloak fragt nur den Schritt, der zur Stufe fehlt. Wer schon auf der Stufe angemeldet ist, wird gar nicht gefragt: Das Fenster geht auf und gleich wieder zu.

Ergebnis: Die wiederholte Anfrage gelingt.

Wann: Die Aktion verlangt ein Höchstalter, etwa 300 Sekunden, und die Anmeldung ist länger her.

  1. 1
    CDMS
    antwortet 401 mit cias.authentication.step-up-required|basic|300
  2. 2
    Frontend
    zeigt „Diese Aktion verlangt eine Anmeldung. Sie darf nicht älter als 5 min sein.“
  3. 3
    Frontend→Keycloak
    meldet neu an, mit acr_values=basic und prompt=login
    prompt=login zwingt Keycloak, wirklich neu anzumelden, auch wenn die Sitzung noch gilt. Die neue Anmeldung ist damit auf jeden Fall frisch, und auth_time im neuen Token rückt vor.
  4. 4
    BFF→CDMS
    wiederholt die Anfrage
    Ergebnis: Die Anmeldung ist jünger als 300 Sekunden, die Anfrage gelingt.

Wann: Die Aktion verlangt eine Stufe, für die der Anmeldeablauf in Keycloak keinen Schritt hat.

  1. 1
    Frontend→Keycloak
    meldet neu an, mit acr_values=mfa
  2. 2
    Keycloak
    kann die Stufe nicht herstellen und übergeht die Bitte still
    Das neue Token trägt die Stufe, die der Ablauf erreicht, hier basic.
  3. 3
    CDMS
    lehnt die wiederholte Anfrage wieder mit 401 ab
  4. 4
    Frontend
    fragt nicht noch einmal, sondern sagt: „Die neue Anmeldung hat das nicht erreicht. Die Aktion wurde nicht ausgeführt.“
    Ergebnis: Keine Schleife. Die Ablehnung bleibt, bis jemand den Anmeldeablauf ergänzt.

Wann: Der Person fehlt die Rolle für die Aktion.

Das Modul prüft immer zuerst das Recht und erst dann die Anmeldung. Ohne Rolle gibt es die gewohnte 403, und nach der Anmeldung wird gar nicht gefragt. Eine stärkere Anmeldung würde die Person ohnehin nicht hereinlassen.

Ergebnis: 403, kein Dialog

Wann: Ein anderes Programm ruft mit dem Token seines eigenen Dienstkontos (Client Credentials) auf.

Ein Dienstkonto kann sich nicht erneut anmelden. Sein Token hat die Stufe basic und keinen Anmeldezeitpunkt. In CDMS und in der Verwaltung von CIAS ist es deshalb von jeder Anforderung ausgenommen. Es ist durch seine Zugangsdaten und Rollen geschützt. Bei Freigaben in CRMS gilt das nicht: Eine Freigabe ist die Unterschrift einer Person, und ein Dienstkonto soll dort gar nicht handeln.

Ergebnis: CDMS und CIAS-Verwaltung: Die Anfrage läuft durch. CRMS-Freigabe: Ablehnung.

Wann: Das Portal lädt die Daten einer Seite schon beim ersten Aufruf auf dem Server.

Auf dem Server kann niemand gefragt werden. Die Ablehnung kommt als Fehler mit der Seite im Browser an. Sobald die Seite dort aufgebaut ist, öffnet das Portal denselben Dialog. Nach der neuen Anmeldung lädt es die Daten der Seite neu.

Ergebnis: Die Seite zeigt danach die Daten.

Bricht die Person den Dialog ab, bleibt die Ablehnung stehen. Die Aktion ist dann nicht ausgeführt.

Eine Schreibanfrage zu wiederholen ist sicher. Die Prüfung der Anmeldung läuft, bevor etwas gespeichert ist. Ein Sonderfall ist die Antwort: Nach einem Anlegen oder Ändern liefert CDMS das gespeicherte Objekt zurück, und das ist ein Lesen. Verlangt das Modell fürs Lesen eine Stufe, gilt sie also auch hier. Lehnt CDMS an dieser Stelle ab, wird die Änderung mit der Ablehnung zurückgerollt.

Was entscheidet über das Ergebnis

Recht vorhanden?Dienstkonto?Stufe reicht?Höchstalter eingehalten?Was passiert
nein–––403, nach der Anmeldung wird nicht gefragt
jaja––läuft durch (außer bei einer Freigabe in CRMS)
janeinnein–401 step-up-required|<stufe>, das Portal fragt
janeinjanein401 step-up-required|<stufe>|<sekunden>, das Portal fragt
janeinjajaDie Aktion läuft

„Höchstalter eingehalten?“ spielt nur eine Rolle, wenn die Aktion eines verlangt. Ohne Höchstalter reicht die Stufe. Die Grenze selbst zählt noch als eingehalten.

Wer entscheidet was

FrageZuständig
Verlangt diese Aktion eine stärkere oder frischere Anmeldung?das Modul, nach seinen eigenen Regeln: CDMS je Modell und Operation, CRMS je Freigabestufe und Dokumentart, CIAS für seine Verwaltung
Wie stark und wann hat sich die Person angemeldet?die Filterkette von CIAS, aus acr und auth_time des mitgeschickten Tokens
Wie sieht die Ablehnung aus?CIAS legt sie fest: 401, ein Schlüssel und der Standard-Header. Jedes Modul antwortet damit gleich
Welche Schritte fragt die Anmeldung ab?Keycloak, nach dem Anmeldeablauf, den der Betreiber eingerichtet hat
Wann wird die Person gefragt, und wie oft wird wiederholt?das Portal: ein Dialog, eine neue Anmeldung, genau eine Wiederholung

CIAS meldet niemanden selbst an und fragt keinen Faktor ab. Es gibt den Stufen nur ihre Namen und sorgt dafür, dass Keycloak genau diese Namen in acr schreibt.

Wo die Anforderung festgelegt wird

Eine Anforderung wird beim Zusammenbau des Systems festgelegt und ist danach fest. Im laufenden System gibt es keinen Weg, sie zu ändern, weder über eine Schnittstelle noch über eine Oberfläche. Wer eine Anforderung senken könnte, könnte den Step-up abschalten.

ModulWas eine Anmeldung verlangen kannWo es festgelegt wirdMehr dazu
CDMSjedes Modell, je Operation (anlegen, lesen, ändern, löschen). Ein Untermodell erbt die Anforderung und kann sie nur verschärfenim Modell, beim Modellieren im HubAnmeldestufe je Modell
CRMSjede Freigabestufe einer Vorlage, dazu endgültige Dokumente je Vorlagenschlüssel, für Lesen und Ändern getrenntbeim Zusammenbau im Hub, im CRMS-Portal: Freigabestufen im Bereich „Freigabe“, Dokumente im Bereich „Anmeldung“. Der Build schreibt sie in die Einstellungen des Systems; die Dokument-Standards sind per Umgebungsvariable überschreibbarFreigabe von Vorlagen
CIASdie eigene Verwaltung in fünf Bereichen (Benutzer, Gruppen, Rollen, Mandanten, Registrierungen), Lesen und Ändern getrenntbeim Zusammenbau im Hub, im CIAS-Portal im Bereich „Verwaltung“. Der Build schreibt sie in die Einstellungen des Systems, überschreibbar per UmgebungsvariableAnmeldestufe für die Verwaltung

Ohne Einstellung verlangt nichts mehr als basic und kein Höchstalter. Das erfüllt jede angemeldete Person.

Jedes Modul meldet CIAS die Stufen an, die es verlangt, so wie seine Rollen. Beim Abgleich vergleicht CIAS sie mit den Stufen, die der Anmeldeablauf in Keycloak herstellen kann. Siehe Module melden ihre Rollen an.

Fallen

Weiter

Suchen