Laufzettel/docs/issues/029-scim-endpunkt.md

#029 M16 – SCIM-Endpunkt als Alternative zum Abgleich

Status: erledigt Im Tracker: #49 Meilenstein: v0.2.0 Labels: phase-2, backend Geschätzt: 12 h Tatsächlich: 4 h 05 min

Ziel

Der Abgleich holt heute. Ein Identitätsanbieter kann auch schicken — authentik, Entra ID und Okta sprechen dafür SCIM 2.0. Das ist der Weg für Häuser, die Laufzettel keinen Lesezugriff auf ihr Verzeichnis geben wollen oder aus einem Netz heraus betreiben, das das Verzeichnis nicht erreicht.

Setzt #028 voraus: die Quellenart SCIM braucht die Weiche.

Zu entscheiden

• Ein Token je Quelle, als Hash gespeichert — Empfehlung, dasselbe Verfahren wie beim lokalen Passwort (argon2). Es wird einmal angezeigt und ist danach nicht mehr lesbar. Das Token identifiziert die Quelle und damit den Kunden; es ist der einzige Mandantenbeweis, den ein Push mitbringt.
• Was bei DELETE /Users/{id} geschieht: aktiv = false, nicht löschen. Das ist die Regel des ganzen Projekts, und ein Identitätsanbieter, der löschen will, bekommt 204 — aber die Zeile bleibt, weil Läufe an ihr hängen. Das muss in der Anleitung stehen, sonst wirkt es wie ein Fehler.

Aufgaben

• Route Handler unter src/app/api/scim/v2/: Users (GET mit Filter userName eq, POST), Users/{id} (GET, PUT, PATCH, DELETE), dazu ServiceProviderConfig, Schemas, ResourceTypes — ohne die drei weigern sich manche Anbieter, überhaupt anzufangen
• Jeder dieser Handler prüft selbst: das Token, und daraus die Quelle und den Kunden. Die Hülle unter (app) liegt hier nicht darüber (CLAUDE.md)
• Zuordnung: externalId → externeId, userName → upn, name.givenName/familyName, emails[primary] → mail, active → aktiv, urn:ietf:params:scim:schemas:extension:enterprise:2.0:User für department und manager
• Antwortform nach RFC 7644: schemas, id, meta.resourceType, meta.location, bei Listen totalResults/itemsPerPage/startIndex; Fehler als urn:ietf:params:scim:api:messages:2.0:Error
• PATCH mit op: add|replace|remove auf den Pfaden, die die Anbieter wirklich schicken — nicht der ganze Standard
• Idempotenz: zweimal dasselbe POST ergibt 409, nicht eine zweite Person
• Protokolleintrag je Vorgang, mit der Quelle als Urheber (Systemlauf, kein Benutzer)
• Admin → Verzeichnis: Token erzeugen, einmal anzeigen, widerrufen; letzte Zustellung sichtbar
• Anleitung Kapitel 06: Einrichtung in authentik und in Entra ID

Akzeptanzkriterien

• Test gegen aufgezeichnete Anfragen von authentik und Entra ID (Form, nicht erfunden): anlegen, aktualisieren, deaktivieren, wieder aktivieren
• Test: ohne Token 401, mit fremdem Token kein Zugriff auf die Personen einer anderen Quelle
• Test: DELETE setzt aktiv = false und löscht nichts
• Test: zweimal dasselbe POST ergibt 409 und keine zweite Zeile
• Test: das Token steht nur als Hash in der Datenbank und in keiner Antwort
• Test: eine Quelle der Art SCIM wird vom Zeitplan nicht abgeglichen — sie bekommt geschickt

Beim Umsetzen dazugekommen

• Zwei Gegenproben blieben grün, und beide deckten etwas auf. Von acht Gegenproben (Regel brechen, Test muss rot werden) schlugen sechs sofort an. Die zwei stillen waren die wertvollen:

  • PATCH remove wirkte gar nicht — ein echter Fehler, kein Testloch. personAendern hatte einen Schalter nurGesetzte, der bei PATCH jedes null als „nicht mitgeschickt“ las und den alten Wert stehen ließ. Nimmt jemand beim Anbieter die Abteilung aus dem Profil, stand sie in Laufzettel weiter — sichtbar, gepflegt aussehend, falsch. Nötig war der Schalter nie: patchAnwenden setzt auf dem vorhandenen Stand auf und liefert deshalb immer einen vollständigen Zielzustand. Der Unterschied zwischen PUT und PATCH liegt vor der Funktion, nicht in ihr. Schalter entfernt, Test ergänzt, Gegenprobe schlägt jetzt an.
  • Entra ID schickt active als Zeichenkette "True"/"False". Das war richtig umgesetzt, aber nur halb geprüft: der Deaktivierungs-Test lief gegen "False", und mit einem reinen value === true kommt dort zufällig das Richtige heraus. Nur das Aktivieren wäre kaputt gewesen — ein Konto, das wieder freigeschaltet wird und in Laufzettel für immer inaktiv bleibt. Der Fehler wäre also nur in einer Richtung sichtbar gewesen. Jetzt steht ENTRA_PATCH_AN mit "True" als eigene aufgezeichnete Form daneben.

• manager war im Issue genannt und wäre fast untergegangen. Die Zuordnung nennt die Enterprise-Erweiterung für department und manager; umgesetzt war zunächst nur die Abteilung. Dazugekommen sind: vorgesetzterAus liest alle drei Formen, die die Anbieter schicken ({value}, {$ref} und die nackte Zeichenkette — letztere nicht standardkonform, aber authentik schickt sie), die Auflösung über die Laufzettel-Kennung, und manager im Schemas-Endpunkt. Das Letzte ist das Entscheidende: ein Anbieter liest dieses Schema und schickt nur, was darin steht. Fehlte es, bliebe der Vorgesetzte dauerhaft leer — ohne Fehlermeldung auf einer der beiden Seiten.

• manager wäre ein Weg über die Quellengrenze gewesen. Eine Kennung aus einer fremden Quelle zeigt auf jemanden, den diese hier nicht sehen darf, und über die Vorgesetzten-Anzeige stünde dessen Name in der Oberfläche. Die Auflösung sucht deshalb nur in der eigenen Quelle; eine Gegenprobe ohne diese Einschränkung ist rot. Dasselbe für den Fall „sein eigener Vorgesetzter“ — die Datenbank weist das ohnehin ab, aber dann wäre die ganze Zuweisung daran gescheitert.

• Ein unbekannter Vorgesetzter lässt die Zuweisung nicht scheitern. Der Anbieter schickt die Leute in beliebiger Reihenfolge. Wer an einer noch unbekannten Kennung scheiterte, ließe die halbe Belegschaft draußen; nachgezogen wird beim nächsten PATCH.

• Ein unverstandener Filter ergibt 400 und nicht „alle Personen“. Das ist die wichtigste Einzelentscheidung dieses Meilensteins. Ihn zu ignorieren hieße, alle zu liefern — und der Anbieter schlösse daraus, die gesuchte Person gäbe es schon, und legte sie nie an. Unterstützt wird genau userName eq "…", die Frage, die jeder Anbieter vor dem Anlegen stellt.

• Ein Fehler im Nachbarcode aus #028: in verbindungTestenAktion stand zweimal dieselbe Bedingung (ergebnis.treffer.length === 0), der zweite Zweig war damit unerreichbar. Genau der Zweig war in #028 als Reviewbefund eingebaut worden — „gelesen, aber nichts zuordenbar“ sollte anders klingen als „der Filter findet niemanden“, weil die Ursachen verschiedene sind und den Administrator an verschiedene Stellen schicken. Wirkungslos, seit er geschrieben wurde. Behoben.

• „Noch nie abgeglichen“ ist an einer SCIM-Quelle eine Falschaussage, und „kein Zeitplan“ liest sich wie ein Mangel. Beides ersetzt: die Pille sagt „nimmt Zustellungen an“, und an der Stelle, an der bei LDAP der Verbindungstest sitzt, steht die letzte Zustellung. Verbindungstest und „Jetzt abgleichen“ gibt es dort nicht — ein Knopf, der nur eine Erklärung auswirft, ist kein Knopf. Wer sie trotzdem über den Dienst ruft, bekommt eine Erklärung statt „unbekannter Fehler“.

• Der Zeitplan lässt SCIM-Quellen aus, und das ist keine Kosmetik. Ein Abgleich, der an einer SCIM-Quelle nichts liest und ERFOLG meldet, hätte über die Abschaltregel die ganze Belegschaft deaktiviert — derselbe Fall, der in #016 einen Reviewbefund gekostet hat. Zwei Stellen halten das: faelligeQuellen nimmt sie nicht auf, und die Weiche im Quellenleser wirft.

• Das Token in keiner Sicht — geprüft nicht an einem Feld, sondern an der ganzen serialisierten Sicht aus Liste und Detail. Ein später ergänztes Feld fällt damit auch auf. Dazu: nicht im Protokolleintrag, nicht im HTML der Seite nach dem Neuladen (in der Klickprobe am gebauten Stand nachgesehen).

• Dieselbe 401 für „kein Token“ und „falsches Token“. Die Unterscheidung wäre eine Auskunft darüber, ob ein geratenes Token die richtige Form hat. Und vor der Hash-Prüfung steht eine Vorab-Prüfung auf das Präfix: ohne sie würde ein Token mit falschem Präfix gegen jeden Hash geprüft, eines mit richtigem nur bis zum Treffer — ein Zeitorakel.

• Die Beschreibungs-Endpunkte verlangen ebenfalls ein Token, und ihre Verneinungen sind der wichtigere Teil: bulk, sort, filter und etag stehen ausdrücklich auf false. Ein Anbieter, der bulk für unterstützt hält, schickt Anfragen, die niemand beantwortet, und meldet das als Fehler der Gegenseite.

• Die Klickprobe am gebauten Stand fand keinen Bedienfehler — zwanzig Prüfungen von „Art SCIM wählbar“ über „Token angezeigt“, eine echte Zustellung mit genau diesem Token, „Person steht in der Liste“, DELETE deaktiviert, Widerruf sperrt, bis „390 px ohne horizontales Scrollen“. Die Probe hat ihre Daten danach selbst wieder entfernt; das ist die Lehre aus #027.

• Ein Test aus #028 war überholt, nicht falsch: er prüfte, dass die Meldung der Weiche „#029“ enthält. Jetzt ist #029 da, und die Antwort bleibt dieselbe — nur ohne Issue-Nummer, denn die Meldung steht auch in der Oberfläche.

Was offen bleibt

• Gegen echte Mandanten ist das nicht gelaufen. Die Anfrageformen in tests/scim.test.ts stammen aus der Dokumentation von authentik und Entra ID, nicht aus einem Mitschnitt — dieselbe Grenze wie bei #028, und sie ist dort im Kopfkommentar der Testdatei benannt. Stimmt eine Form nicht, stimmen Test und Wirklichkeit nicht. Die Prüflisten für den ersten echten Lauf stehen in docs/betrieb/scim.md unter „Prüfen von Hand“.
• Keine Paginierung über 200 Einträge bei GET /Users ohne Filter. Die Anbieter fragen gefiltert; ein voller Abzug ist keine Betriebsart dieses Endpunkts.
• Kein /Groups. Rollen entstehen beim Anmelden aus den OIDC-Gruppen, nicht aus dem Provisioning. ResourceTypes nennt deshalb nur User.