Abgleich mit Keycloak

Worum es geht

Jede Gruppe lebt an zwei Orten: in der CIAS-Datenbank und als Kopie in Keycloak. Eine Änderung schreibt beide nacheinander, und dazwischen kann etwas schiefgehen. Keycloak ist kurz weg, oder der Prozess bricht genau zwischen den beiden Schritten ab. Dann ist CIAS richtig, aber die Kopie hinkt hinterher.

Der Sync-Zustand macht das sichtbar, und der Abgleich repariert es.

Die zwei Zustände

stateDiagram-v2
    [*] --> PENDING: Gruppe angelegt
    PENDING --> SYNCHRONIZED: Keycloak hat die Änderung angenommen
    SYNCHRONIZED --> PENDING: Gruppe geändert (vor dem Keycloak-Schritt)
    PENDING --> PENDING: Keycloak nicht erreichbar
    SYNCHRONIZED --> PENDING: Mitglied aufnehmen gescheitert
    PENDING --> SYNCHRONIZED: Abgleich

Zustand	Bedeutung	Was du tust
`SYNCHRONIZED`	CIAS und Keycloak stimmten beim letzten Schreiben überein	nichts
`PENDING`	in Keycloak steht noch nicht alles, was CIAS führt. Den Personen fehlen also womöglich Rollen	Abgleich starten

CIAS setzt PENDING, bevor es Keycloak anfasst, nicht erst, wenn Keycloak scheitert. Stürbe der Prozess zwischen den beiden Schritten, bliebe ein Zustand, der nur beim Scheitern gesetzt wird, sauber, obwohl die Kopie fehlt. Genau für diesen Fall gibt es den Zustand.

Wann eine Gruppe PENDING bleibt:

Anlegen oder Ändern, und Keycloak nimmt die Kopie nicht an.
Mitglieder aufnehmen, und Keycloak nimmt nicht alle auf.
Eine Standardgruppe bekommt nach einer Registrierung ein neues Mitglied, und Keycloak ist nicht erreichbar, siehe Die Standardgruppe.

Nehmen hinterlässt nie PENDING: Scheitert Keycloak beim Entfernen oder Löschen, scheitert der ganze Aufruf, und CIAS bleibt, wie es war. Siehe Gruppen und Mitglieder verwalten.

Was ein Abgleich tut

Ein Abgleich, Gruppe für Gruppe

1

CIAS
liest alle Gruppen aus der CIAS-Datenbank
2

CIAS→Keycloak
je Gruppe: Kopie anlegen, falls sie fehlt. Beschreibung, Standardgruppe, Realm-Rollen und Client-Rollen genau auf den Stand von CIAS setzen, auch Clients leeren, die die Gruppe nicht mehr trägt
3

CIAS→Keycloak
je Gruppe: Mitglieder angleichen. Erst entfernen, wer in Keycloak zu viel ist, dann aufnehmen, wer fehlt
4

CIAS
je Gruppe: SYNCHRONIZED setzen. Scheitert eine Gruppe, kommt sie mit Grund in den Bericht, die anderen laufen weiter
5

CIAS→Keycloak
liest alle Gruppen mit Marke cias-managed und löscht die, die CIAS nicht mehr kennt

Ergebnis: Bericht: angelegt, abgeglichen, entfernt, gescheitert

Die Reihenfolge ist Absicht. Würde CIAS zuerst löschen, könnte es eine Gruppe löschen, die derselbe Lauf gleich wieder anlegt. Am Ende stimmte alles, aber unterwegs hätten alle Mitglieder kurz ihre Rechte verloren.

Ein Abgleich schaut jede Gruppe an, nicht nur die PENDING-Gruppen. Auch eine Gruppe, die sauber aussieht, kann nach einem Abbruch oder einer Handänderung in Keycloak abweichen. Stimmt eine Gruppe schon, kostet sie nur Lesezugriffe.

Wann abgeglichen wird

Zwei Anlässe

beim Startauf Anforderung

Wann: Die Anwendung ist hochgefahren, und codamai.cias.authorization.startup.enabled ist true.

Nach dem Start läuft ein Abgleich ohne Aufrufer. Das Ergebnis steht im Log: eine Zeile mit den Zahlen, oder eine Warnung mit den gescheiterten Gruppen. Scheitert der Lauf, startet die Anwendung trotzdem. Eine Gruppe ohne Kopie ist schlecht, aber besser als eine Plattform, die nicht hochkommt, weil Keycloak gerade neu startet. Die Einstellung ist ohne Angabe false; das eigenständige CIAS setzt sie nicht.

Ergebnis: Bericht im Log

Wann: Ein Plattform-Administrator ruft POST /cias/admin/groups/reconcile auf.

Derselbe Lauf. Wer kein Plattform-Administrator ist, bekommt 403 cias.authorization.denied.

Ergebnis: 200 mit dem Bericht, auch wenn Gruppen gescheitert sind

Warum kein Zeitgeber? Würde ein Hintergrundlauf Abweichungen mal reparieren und mal nicht, sähe niemand von außen, ob eine Abweichung gerade besteht oder schon behoben ist. Deshalb gibt es genau zwei Anlässe, und beide entscheidet ein Mensch: das Starten der Anwendung und der Aufruf.

Der Bericht

Anfrage

POST /cias/admin/groups/reconcile
Authorization: Bearer <Token eines Plattform-Administrators>

Antwort

HTTP 200
{
  "created":  ["einkauf"],
  "repaired": ["grundrechte", "support"],
  "removed":  ["alt-vertrieb"],
  "failed":   [
    { "group": "lager", "reason": "…" }
  ]
}

Feld	Bedeutung
`created`	Gruppen, deren Kopie in Keycloak fehlte und jetzt da ist
`repaired`	Gruppen, deren Kopie es schon gab. Sie wurden geprüft und bei Bedarf auf den Stand von CIAS gebracht
`removed`	Gruppen mit Marke `cias-managed`, die CIAS nicht mehr kennt, jetzt in Keycloak gelöscht
`failed`	was nicht ging, je Gruppe mit Grund. Leer heißt: alles erledigt

Der Aufruf antwortet mit 200, auch wenn failed Einträge hat. Ein einziger Statuscode für vierzig Gruppen würde verschweigen, welche Gruppe das Problem hat. Konnte CIAS die Gruppenliste aus Keycloak gar nicht lesen, steht in failed ein Eintrag (provider listing), und CIAS löscht in diesem Lauf nichts.

Die Entscheidung

Was macht der Abgleich mit einer Gruppe?

In CIAS?	In Keycloak mit Marke `cias-managed`?	Ergebnis
ja	nein	in Keycloak anlegen, Rollen und Mitglieder setzen → `created`
ja	ja	auf den Stand von CIAS bringen → `repaired`
nein	ja	in Keycloak löschen → `removed`
nein	nein, Gruppe ohne Marke	nicht anfassen, CIAS sieht sie gar nicht