Befristete Rollen

Worum es geht

Manche Rechte gelten nur eine Zeit lang: für die Dauer eines Projekts, während einer Urlaubsvertretung, ab dem ersten Arbeitstag. Keycloak kennt so etwas nicht. Dort hat eine Person eine Rolle oder nicht. CIAS führt deshalb das Zeitfenster einer Vergabe selbst und bringt Keycloak auf den Stand, wenn die Zeit gekommen ist.

Eine Vergabe kann einen Beginn (validFrom) und ein Ende (validUntil) haben, beide als Zeitpunkt mit Uhrzeit, beide optional. Ohne beide ist es eine gewöhnliche, unbefristete Vergabe, und das ist der Normalfall.

Die vier Zustände

stateDiagram-v2
    direction LR
    [*] --> SCHEDULED: vergeben, Beginn in der Zukunft
    [*] --> ACTIVE: vergeben, ohne Beginn oder Beginn erreicht
    SCHEDULED --> ACTIVE: Beginn erreicht (Zeitgeber)
    ACTIVE --> EXPIRED: Ende überschritten (Zeitgeber)
    SCHEDULED --> EXPIRED: Ende überschritten, bevor sie begann
    SCHEDULED --> REVOKED: entzogen
    ACTIVE --> REVOKED: entzogen
    EXPIRED --> [*]
    REVOKED --> [*]

Zustand	Bedeutung	In Keycloak eingetragen
`SCHEDULED`	gespeichert, Beginn liegt in der Zukunft	nein
`ACTIVE`	gilt	ja
`EXPIRED`	Ende überschritten, endgültig	nein
`REVOKED`	vorher entzogen, endgültig	nein

EXPIRED und REVOKED sind verschiedene Zustände, obwohl die Person in beiden Fällen die Rolle nicht mehr hat. Ein Audit muss beantworten können, warum jemand ein Recht verlor: weil die Zeit ablief oder weil es jemand entzog. Deshalb wird eine abgelaufene Vergabe auch nachträglich nicht mehr entzogen: 409 cias.authorization.invalid-state.

Der Zeitstrahl

gantt
    dateFormat YYYY-MM-DD
    axisFormat %d.%m.
    section Vertretung Ben
    vergeben, SCHEDULED       :done, 2026-09-22, 2026-10-01
    ACTIVE, Rolle in Keycloak :active, 2026-10-01, 2026-10-15
    EXPIRED                   :crit, 2026-10-15, 2026-10-20

Anfrage

POST /cias/admin/role-assignments
{
  "userId": "8c1d…",
  "roleClient": "cdms-backend",
  "roleKey": "invoice-approve",
  "tenantKey": "nordbau",
  "validFrom": "2026-10-01T06:00:00Z",
  "validUntil": "2026-10-15T18:00:00Z",
  "reason": "Urlaubsvertretung für Anna"
}

Antwort

HTTP 200
{ "id": "d207…", "state": "SCHEDULED", … }

Beide Grenzen zählen mit: Genau zum Zeitpunkt validUntil gilt die Vergabe noch, danach nicht mehr. Ende vor Beginn lehnt CIAS ab: 400 cias.authorization.invalid-request. Ein Ende, das schon vorbei ist, ebenfalls: 422 cias.authorization.validity-window-ended. Gespeichert wird dann nichts, und in Keycloak kommt nichts an.

Noch einmal vergeben: das Fenster ändern

Je Person, Rolle und Mandant gibt es höchstens eine laufende Vergabe (SCHEDULED oder ACTIVE). Wer dieselbe Rolle noch einmal vergibt, legt deshalb keine zweite an, sondern ändert die bestehende:

Dieselbe Rolle noch einmal vergeben

Fenster und Grund	Zustand vorher	Was passiert
gleich	beliebig	nichts; CIAS liefert die bestehende Vergabe zurück, ohne neues Ereignis
anders	ACTIVE	Vergabe übernimmt Fenster und Grund; Ereignis `WindowChanged`
Beginn neu in der Zukunft	ACTIVE	erst aus Keycloak austragen, dann `SCHEDULED`; der Zeitgeber trägt sie bei Beginn wieder ein
Beginn jetzt erreicht	SCHEDULED	`ACTIVE` und in Keycloak eingetragen, sofern das Konto in Betrieb ist; sonst bleibt sie geplant
Ende schon vorbei	beliebig	422 `cias.authorization.validity-window-ended`, die Vergabe bleibt, wie sie war

So verlängerst du eine Vertretung: dieselbe Rolle mit dem neuen validUntil noch einmal vergeben. grantedBy bleibt die ursprüngliche Vergabe, wer das Fenster geändert hat, steht im Ereignis.

Der Zeitgeber

Ein Zeitgeber ist ein Job, der in festen Abständen läuft. Hier sucht er alle Vergaben, deren Zustand nicht mehr zur Uhrzeit passt, und bringt sie in Ordnung.

Was der Zeitgeber je Vergabe tut

Beginn erreichtEnde überschrittenFehler bei einer Vergabe

Wann: SCHEDULED, und validFrom ist vorbei

1

CIAS
setzt die Vergabe auf ACTIVE
2

CIAS→Keycloak
trägt die Rolle ein

Ergebnis: Event Activated. Erst speichern, dann Keycloak: Scheitert Keycloak, verweigert das eher, und der nächste Lauf holt es nach.

Wann: ACTIVE oder SCHEDULED, und validUntil ist vorbei

1

CIAS→Keycloak
trägt die Rolle aus, falls sie eingetragen war
2

CIAS
setzt die Vergabe auf EXPIRED

Ergebnis: Event Expired. Erst Keycloak, dann speichern: Die Person verliert die Rolle auch dann, wenn danach etwas scheitert.

Wann: Keycloak ist für diese eine Vergabe nicht erreichbar.

Der Zeitgeber vermerkt sie und macht mit der nächsten weiter. Beim nächsten Lauf versucht er es wieder.

Ergebnis: Im Log steht eine Warnung mit den Vergaben, die nicht fertig wurden. Jede davon ist ein Recht, das jemand noch hat und nicht mehr haben sollte.

Einstellung	Standard	Bedeutung
`codamai.cias.authorization.synchronization.enabled`	im Starter aus, im eigenständigen CIAS an	ob der Zeitgeber läuft
`codamai.cias.authorization.synchronization.interval`	`PT5M`	Pause zwischen zwei Läufen

Laufen mehrere Instanzen, darf der Zeitgeber auf allen laufen. Treffen zwei auf dieselbe Vergabe, verliert eine die Sperre auf den Datensatz, und der nächste Lauf erledigt den Rest. Die Aufrufe an Keycloak lassen sich gefahrlos wiederholen. Wer genau einen Lauf will, schaltet den Zeitgeber ab und ruft den Abgleich aus einem eigenen Zeitplan auf.

Wann es im Token ankommt

Zwischen dem Zeitpunkt im Datensatz und dem, was eine Anwendung sieht, liegen zwei Verzögerungen:

bis zu einem Intervall des Zeitgebers, standardmäßig 5 Minuten
bis das Token der Person erneuert wird: Das alte Token trägt noch den alten Stand

Eine Vergabe mit Ende 18:00 Uhr kann also noch einige Minuten nach 18:00 Uhr wirken. Siehe Warum ein Rechteentzug verzögert wirkt.

Fallen

Weiter

Eine Rolle vergeben
Eine Rolle entziehen
Zum Vergleich: das Gültigkeitsfenster eines Mandanten, Mandanten sperren, schließen, Gültigkeit