Technische Beschreibung zur Anbindung an das Active-Directory

Überblick

Die Lösung dient zur automatisierten Synchronisation von Benutzerkonten und Gruppeninformationen zwischen Microsoft Active Directory (AD) und Solventum™ Fluency Direct™.

Auf Klinikseite läuft ein lokaler Collector, der relevante AD-Daten einliest, als strukturiertes JSON-Payload aufbereitet und an einen zentralen Backend-Endpunkt überträgt. Die zentrale Verarbeitung wertet die gelieferten AD-Daten aus und führt die erforderlichen Aktionen für Solventum™ Fluency Direct™ aus, insbesondere die Benutzeranlage, -deaktivierung, -reaktivierung sowie die Verwaltung von Gruppenzuordnungen einzelner User.

Dabei werden folgende Aufgaben durchgeführt

Lesen relevanter Benutzer aus dem Active Directory
Lesen relevanter Gruppen und Gruppenmitgliedschaften aus dem Active Directory
Erzeugen eines standardisierten JSON-Payloads
Lokaler Export des Payloads zu Prüf- und Supportzwecken
Übertragung des Payloads an den zentralen Backend-Endpunkt
Weiterverarbeitung der Daten für Solventum™ Fluency Direct™

Systemvoraussetzungen

Betriebssystem / Laufzeit

Windows Server oder Windows Client
Windows Powershell 5.1 oder Powershell 7+

Erforderliche Komponenten

Active-Directory-Modul (RSAT)
Zugriff auf einen Domain-Controller

Netzwerkzugriffe

Die folgenden Systeme müssen erreichbar sein:

Active Directory Domain-Controller
Zentraler Backend-Ednpunkt

Installation und Bereitstellung

Das Installationspaket enthält die benötigten PowerShell-Skripte, die Konfigurationsvorlage und die Laufzeitdateien für den Collector. Die Installation erfolgt immer in ein fest definiertes Zielverzeichnis:

C:\Program Files\FftAdSyncCollector

Im Installationspaket enthalten sind:

Install.ps1
Uninstall.ps1
README.txt
.env.example
src
reports
run

Nach der Installation liegt die für Sie spezifische Konfiguration in der Datei .env im Installationsverzeichnis.

Konfiguration

Die Konfiguration erfolgt über eine lokale .env-Datei im Installationsverzeichnis. Wichtige Parameter:

CUSTOMER_ID	Eindeutige Kundenkennung zur Zuordnung im Backend
COMPANY_ID	Eindeutige Company-Kennung zur Zuordnung im Backend; kann von der Nummer in Customer_ID abweichen
AD_SERVER	Domain-Controller bzw. Active Directory Server
SYNC_GROUPS	Explizite Liste der zu synchronisierenden AD-Gruppen; alternativ SYNC_USERS_OU_DN als OU-basierter Fallback
SYNC_USERS_OU_DN	Aktiviert zusätzliche Debug-Ausgaben
DEBUG_LOGGING	Intervall für den Hintergrundlauf in Sekunden
COLLECTOR_INTERVAL_SECONDS	Basis-URL des Backend-Endpunkts
BACKEND_API_TOKEN	Bearer-Token für den Backend-Zugriff
BACKEND_SUBMIT_PATH	Pfad des Submit-Endpunkts
SYNC_PAYLOAD_EXPORT_PATH	lokaler Exportpfad für das JSON-Payload

Beispielwerte sind in der Datei .env.example enthalten.

Hinweis:

Wenn SYNC_GROUPS gesetzt ist, werden nur die dort definierten AD-Gruppen synchronisiert. Für einfache Gruppennamen kann eine kommagetrennte Liste verwendet werden. Bei Distinguished Names oder Gruppennamen mit Kommas bitte Semikolon oder Zeilenumbrüche als Trenner verwenden. SYNC_USERS_OU_DN bleibt als Fallback für Bestandskonfigurationen verfügbar.

Datenbasis und Benutzerabgleich

Der Collector liest Benutzer und Gruppen aus dem definierten Active-Directory-Bereich aus und übergibt diese Daten an die zentrale Verarbeitung.

Verwendete AD-Attribute:

SameAccountName
UserPrincipalName
Mail
Enabled
DisplayName
Gruppenmitgliedschaften

Die fachliche Zuordnung erfolgt zentral auf Basis der gelieferten AD-Daten. Für die Verarbeitung werden die tatsächlichen Benutzernamen verwendet. Für Solventum™ Fluency Direct™-Gruppen wird der zentrale Gruppenkatalog verwendet. Dabei wird der Gruppenname angezeigt, die eigentliche Zuordnung erfolgt über die interne Gruppen-ID bzw. goid.

Synchronisationslogik

Ermittlung relevanter Benutzer

Ein Benutzer wird in die Synchronisation aufgenommen, wenn er direkt im definierten Synch-Bereich liegt oder Mitglied einer relevanten Gruppen innerhalb dieses Bereichs ist.

Zentrale Verarbeitung

Die zentrale Verarbeitung kann abhängig von den gelieferten Daten folgende Aktionen ausführen:

Anlegen fehlender Benutzer
Deaktivieren nicht mehr berechtigter Benutzer
Reaktivieren erneut berechtigter Benutzer
Setzen von Gruppenmitgliedschaften
Aktualisieren von Statusinformationen

Gruppenlogik

Die Gruppenzuordnung wird zentral gegen den aktuellen Gruppenkatalog aufgelöst. Für Solventum™ Fluency Direct™ wird beim Schreiben die interne Gruppen-ID verwendet. Der Gruppenname dient nur der lesbaren Darstellung.

Hintergrundbetrieb

Betriebsarten

Der Collector kann manuell oder automatisiert ausgeführt werden. Mögliche Betriebsarten:

Manueller Einzelstart per PowerShell
Regelmäßiger Hintergrundlauf über ein Loop-Skript
Automatischer Start über eine geplante Windows-Aufgabe

Für den produktiven Betrieb wird eine automatische Hintergrundausführung empfohlen. Das Ausführungsintervall wird über COLLECTOR_INTERVAL_SECONDS gesteuert.

Geordnetes Stoppen

Der Collector kann über eine Stop-Datei sauber beendet werden. Dazu können Sie im Installationsverzeichnis die Datei

C:\Program Files\FftAdSyncCollector\run\stop.signal

anlegen. Der laufende Collector erkennt diese Datei und beendet sich anschließend geordnet. Die Datei kann nach dem Stop wieder entfernt werden.

Logging und Fehlerbehandlung

Die Anwendung erzeugt Protokolle und Exportdateien zur Nachvollziehbarkeit der Verarbeitung. Typische Aufgaben:

Logdateien

C:\Program Files\FftAdSyncCollector\reports\main.log

Exportiertes JSON-Payload

C:\Program Files\FftAdSyncCollector\reports\syncpayload.json

Das Logging ist bewusst knapp gehalten und verwendet vor allem INFO- und ERROR-Meldungen. Vor dem Lauf prüft der Collector wichtige Voraussetzungen wie die .env-Datei, die Laufzeitdateien und das Active-Directory-Modul. Wenn Voraussetzungen fehlen, wird der Start frühzeitig abgebrochen und die Ursache im Log dokumentiert.

Sicherheit

Zugangsdaten werden nicht im Quellcode gespeichert
Die Konfiguration erfolgt lokal über die .env-Datei
Der Zugriff auf den zentralen Endpunkt erfolgt ausschließlich verschlüsselt über HTTPS.
Der Bearer-Token für den Backend-Zugriff ist vertraulich zu behandeln.