Laufzettel/docs/issues/016-verzeichnis-ldap.md

#016 M11 – Verzeichnis und LDAP-Abgleich

Status: erledigt Meilenstein: v0.1.0 Labels: phase-1, backend, frontend, security Geschätzt: 12 h Tatsächlich: 3 h 25 min

Ziel

Die Mitarbeiter der eigenen Firma kommen aus dem Active Directory, damit beim Start eines Laufs nichts abgetippt werden muss. Gilt nur für die eigene Organisation; im Modus DIENSTLEISTUNG ist das Verzeichnis-Modul ausgeblendet.

Aufgaben

• ldapts 9.x: ldaps bevorzugt, StartTLS optional, eigenes CA-Zertifikat hinterlegbar (caCertPem), minVersion: TLSv1.2
• searchPaginated mit pageSize: 1000 — nicht search mit paged, das puffert alles im Speicher
• explicitBufferAttributes: ['objectGUID'] und korrekte Umsortierung der gemischt-endianen Bytes zur GUID-Zeichenkette als externeId
• Standardfilter (&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))
• Attribut-Mapping mit AD-Vorgaben: givenName, sn, displayName, mail, userPrincipalName → upn, sAMAccountName → sam, department, title, manager → vorgesetzterExterneId, distinguishedName → dn
• „Verbindung testen“: zeigt die ersten 10 Treffer mit gemappten Feldern, ohne etwas zu schreiben
• abgleichService: anlegen, aktualisieren, verschwundene oder deaktivierte Konten auf aktiv = false — nie löschen; Ergebnis (angelegt/aktualisiert/deaktiviert/Fehler) in letzterAbgleichStatus, letzterAbgleichFehler, letzterAbgleichAm und im Protokoll
• Zeitplan mit node-cron im selben Prozess, Intervall je Quelle (Standard 60 min), Sperre über AbgleichSperre in der Datenbank, damit nur eine Instanz läuft; zusätzlich „Jetzt abgleichen“
• Bind-Passwort verschlüsselt über src/lib/geheimnisse.ts, Serializer entfernt bindPasswortVerschluesselt aus jeder Antwort
• Admin → Verzeichnis: Quelle anlegen und bearbeiten, Verbindung testen, Abgleich-Status und -Log, „Jetzt abgleichen“
• Manuelle Mitarbeiter und CSV-Import (givenName, sn, displayName, mail, upn, sam, department, title)
• Abteilungsvorschläge aus den department-Werten des Abgleichs, vom Admin in Abteilung-Einträge übernehmbar
• Nur die gemappten Attribute speichern: keine Passwörter, keine Gruppenmitgliedschaften des Mitarbeiters
• docker-compose.test.yml um OpenLDAP erweitern, mit AD-ähnlichem Fixture-Schema (sAMAccountName, userPrincipalName, binäres objectGUID) — aus #005 hierher verschoben, weil der Dienst erst hier benutzt wird
• Screenshots Verzeichnis, Verbindungstest, Abgleich-Log, CSV-Import in docs/screenshots/m11/

Akzeptanzkriterien

• Integrationstest gegen den Container: erster Lauf legt Mitarbeiter an, zweiter Lauf aktualisiert sie ohne Duplikate
• Integrationstest: ein aus dem Verzeichnis entferntes Konto wird aktiv = false und bleibt in der Datenbank
• Integrationstest: ein per userAccountControl deaktiviertes Konto wird aktiv = false
• Test: {{ou}} wird korrekt aus dem dn abgeleitet
• Test: objectGUID als Buffer ergibt reproduzierbar dieselbe GUID-Zeichenkette (bekannter Byte-Vektor als Fixture)
• Test: keine API-Antwort und kein Server-Log enthält das Bind-Passwort im Klartext
• Test: zwei gleichzeitig gestartete Abgleiche derselben Quelle — der zweite wird von der Sperre abgewiesen
• Im Modus DIENSTLEISTUNG ist Admin → Verzeichnis nicht erreichbar

Ergebnis

Erledigt am 2026-09-26. 1098 Tests (vorher 980) und 71 Ende-zu-Ende-Tests (vorher 67) grün, Screenshots in docs/screenshots/m11/.

Über die Vorgabe hinaus entstanden drei Dinge, die der Review verlangt hat und die zum Kern der Sache gehören:

• Eine Notbremse gegen den teuersten Fehler. Lässt sich kein einziger gelesener Eintrag zuordnen, wird niemand deaktiviert — der Lauf meldet einen Fehler mit Namen. Ein Tippfehler im Kennungsattribut hätte sonst die gesamte Belegschaft abgeschaltet und dabei ERFOLG gemeldet.
• Die Attributzuordnung ist in der Oberfläche bearbeitbar. Vorher stand sie nur in der Datenbank, obwohl Code und Hilfetext etwas anderes versprachen.
• Ein Abgleich-Log je Quelle mit den letzten zehn Läufen: gelesen, angelegt, übernommen, aktualisiert, deaktiviert, übersprungen — und wer sie angestoßen hat, Mensch oder Zeitplan.

Der unabhängige Review

Ein Blocker, acht Befunde, sieben Anmerkungen:

• Blocker: Abgleich ohne zuordenbare Einträge schaltete alle ab. Siehe oben. Das Log hat den Fall danach selbst dokumentiert — der Lauf um 01:20 zeigt „3 deaktiviert, 4 übersprungen“.
• Übersprungene Einträge wurden mitdeaktiviert, obwohl sie im Ergebnis standen.
• VerbindungsFehler erbte nicht von VerzeichnisFehler: falsches Passwort, falscher Basis-DN und ein toter Server sahen in der Oberfläche identisch aus.
• Ergebniscodes wie 0x31 standen roh in der Meldung.
• Bei einem Abbruch mitten im Lesen stand „angelegt: 1500, gelesen: 0“.
• faelligeQuellen fragte ohne Mandantengrenze.
• Eine von Hand angelegte Person mit demselben sam wurde vom Abgleich verdoppelt.
• Ein hinterlegtes CA-Zertifikat war unsichtbar und nicht entfernbar.
• Die Intervallgrenzen liefen auseinander: 1440 Minuten in der Oberfläche, 10080 im Dienst.