Active Directory Directory Connector

Der Active Directory Directory Connector ist eine FoxIDs-Komponente, die die Directory Connector-API für eine AD/LDAP-Domäne implementiert.

Installieren Sie die Komponente in der Windows-Umgebung des Kunden, in der sie die Domänencontroller erreichen kann. FoxIDs ruft die Komponente über HTTPS auf, und die Komponente validiert Benutzer, ändert Kennwörter, setzt Kennwörter und gibt Benutzereigenschaften und Claims aus Active Directory zurück.

Der Connector wird auf dem Windows/IIS-Server nahe Active Directory installiert und konfiguriert. In FoxIDs wird er anschließend in der FoxIDs-Umgebung unter Settings > Environment > Directory connector settings aktiviert, wo API URL und Secret des Connectors konfiguriert werden.

Die Komponente wird als Windows-Zip zusammen mit FoxIDs-Versionen veröffentlicht:

FoxIDs.DirectoryConnector.ActiveDirectory-{version}-win-x64.zip

Endpoints

Die Komponente stellt folgende Endpunkte bereit:

• GET /health
• POST /authentication
• POST /change-password
• POST /set-password

Der Endpoint /health ist nicht authentifiziert und gibt nur minimale Statusinformationen zurück. Er prüft die erforderliche Konfiguration, AD-Bind, den Zugriff auf die User Search Base und optional den Zugriff auf die Group Search Base. Delegierte Rechte für set-password / password reset werden nicht getestet. Detaillierte Fehler und Stack Traces werden auf dem Server protokolliert und nicht vom Endpunkt zurückgegeben.

Beispielantwort:

{
	"status": "ok",
	"adBind": "ok",
	"userSearch": "ok",
	"groupSearch": "not_configured"
}

Die Antwort enthält nur status, adBind, userSearch und groupSearch. status ist nur dann ok, wenn die erforderliche Konfiguration gültig ist, der AD-Bind erfolgreich ist, der Zugriff auf die User Search Base erfolgreich ist und der Zugriff auf die Group Search Base nicht fehlgeschlagen ist. groupSearch ist not_configured, wenn keine Group Search Base konfiguriert ist. Wenn eine Prüfung nicht durchgeführt werden kann, weil eine frühere Prüfung fehlgeschlagen ist oder Konfiguration fehlt, wird das Feld als unknown zurückgegeben.

Anforderungen

• Windows Server mit IIS.
• ASP.NET Core Hosting Bundle für .NET 10.
• Netzwerkzugriff vom IIS-Server auf den konfigurierten Domänencontroller.
• LDAPS oder ein anderer sicherer Kanal für Kennwortoperationen.
• Eine AD-Domäne pro Connector-Deployment.
• Ein Domänen-Servicekonto, wenn konfigurierte Credentials verwendet werden.
• Delegierte AD-Berechtigung zum Password Reset, wenn set-password unterstützt werden soll.

Ein domänenverbundener IIS-Server, dessen Application Pool als Domänen-Servicekonto ausgeführt wird, ist die empfohlene Konfiguration. Konfigurierte Bind-Credentials werden auch über appsettings.json oder Umgebungsvariablen unterstützt.

Authentifizierung

Konfigurieren Sie einen starken API-Schlüssel in appsettings.json. FoxIDs sendet HTTP Basic authentication mit API ID directory_connector und dem konfigurierten Secret.

Verwenden Sie den Header X-FoxIDs-Api-Key: <api-key> nur, wenn ein Reverse Proxy vor dem Directory Connector Basic Authentication verarbeitet, bevor die Anforderung die Komponente erreicht, und api-key umschreibt.

AD-Suche und Bindung

Die Komponente sucht zuerst mit der konfigurierten Serviceidentität in AD. Sie unterstützt die Suche über:

• E-Mail
• Telefon
• Benutzername
• directoryUserId, wenn FoxIDs diesen Wert bereits kennt

Der Benutzer wird in FoxIDs mit der AD-objectGUID identifiziert, die als base64 codiert ist. Der Wert wird als directoryUserId zurückgegeben und bleibt stabil, auch wenn E-Mail, Telefon oder Benutzername geändert werden.

Bei der Kennwortauthentifizierung ermittelt die Komponente den Distinguished Name des Benutzers und bindet anschließend als dieser Benutzer mit dem übermittelten Kennwort an AD. Dadurch werden mehrdeutige Benutzerauflösungen vermieden und alle konfigurierten Identifikatortypen unterstützt.

Bei einer Kennwortänderung validiert AD das aktuelle Kennwort und die Kennwortrichtlinie.

Wenn die FoxIDs-Kennwortrichtlinie für den Directory Connector aktiviert ist, validiert FoxIDs Kennwortlänge, Komplexität und Kennworthistorie vor dem Aufruf des Connectors vorab. Dadurch erhält der Benutzer präzisere Rückmeldungen für diese Prüfungen. AD bleibt maßgeblich und kann das Kennwort danach weiterhin mit password_not_accepted ablehnen, z. B. aufgrund von Mindestlänge, Komplexität, Kennworthistorie, minimum password age, fine-grained password policy oder einem custom password filter.

Für set-password muss die konfigurierte Serviceidentität delegierte Rechte für reset-password besitzen.

Zugriff für das AD-Servicekonto

Der Connector sollte mit einer dedizierten AD-Serviceidentität ausgeführt werden. Machen Sie diese Identität nicht zum Domänenadministrator. Verwenden Sie einen normalen Domänenbenutzer oder eine benutzerdefinierte Sicherheitsgruppe und delegieren Sie nur die erforderlichen Berechtigungen auf den OUs, die der Connector verwendet.

Für Benutzersuche und Authentifizierung muss die Connector-Identität berechtigt sein, jede konfigurierte UserSearchBases-OU zu durchsuchen und die vom Connector verwendeten Benutzerobjekte und Attribute zu lesen. Eine neue dedizierte AD-Serviceidentität hat diesen Lesezugriff häufig bereits standardmäßig, sofern die AD-ACLs nicht eingeschränkt wurden.

Für die Kennwortauthentifizierung findet der Connector den Benutzer zunächst mit der Serviceidentität und bindet sich dann mit dem übermittelten Kennwort als dieser Benutzer an AD. Dazu muss die Serviceidentität das Kennwort des Benutzers nicht kennen oder zurücksetzen.

Bei einer Kennwortänderung, bei der der Benutzer das aktuelle Kennwort angibt, verwendet der Connector das AD-Verhalten für password change, und AD validiert das aktuelle Kennwort und die Kennwortrichtlinie.

Für set-password / password reset müssen Kennwortzurücksetzungsrechte auf den Benutzerobjekten in jeder konfigurierten UserSearchBases-OU delegiert werden, in der der Connector password reset unterstützen soll. Klicken Sie in Active Directory Users and Computers mit der rechten Maustaste auf die vom Connector verwendete Benutzer-OU, wählen Sie Delegate Control..., wählen Sie die Connector-Identität aus und wählen Sie im Schritt Tasks to Delegate die Option Reset user passwords and force password change at next logon.

Delegieren Sie außerdem zusätzliche kennwortbezogene Berechtigungen, die von der Domänenrichtlinie verlangt werden, nur wenn die Umgebung diese Vorgänge verwendet. Für Gruppenrollen-Claims benötigt die Connector-Identität Lesezugriff auf die konfigurierten GroupSearchBases. Sie muss die Group OU auflisten und Gruppenattribute wie cn, distinguishedName und member lesen können.

Konfiguration

Die Konfiguration verwendet die Standard-.NET-Konfiguration. Werte können in appsettings.json, Umgebungsvariablen, IIS-Konfiguration oder einem anderen .NET-Konfigurationsprovider gesetzt werden.

Beispiel:

{
	"DirectoryConnector": {
		"ApiKey": "change-me",
		"ActiveDirectory": {
			"Domain": "example.local",
			"Server": "dc01.example.local",
			"Port": 636,
			"UseSsl": true,
			"Bind": {
				"Mode": "Integrated",
				"Username": "",
				"Password": ""
			},
			"UserSearchBases": [
				"OU=Users,DC=example,DC=local"
			],
			"GroupSearchBases": [
				"OU=Groups,DC=example,DC=local"
			],
			"UserIdentifiers": {
				"Username": "sAMAccountName",
				"Email": "mail",
				"Phone": "telephoneNumber"
			},
			"Claims": [
				{
					"Claim": "name",
					"Attribute": "displayName"
				},
				{
					"Claim": "given_name",
					"Attribute": "givenName"
				},
				{
					"Claim": "family_name",
					"Attribute": "sn"
				}
			],
			"GroupClaims": [
				{
					"Claim": "role",
					"GroupDistinguishedName": "CN=Employees,OU=Groups,DC=example,DC=local",
					"IncludeNestedGroups": true,
					"Value": "employees"
				}
			]
		}
	}
}

DirectoryUserId wird immer aus der AD-objectGUID abgeleitet und Base64-codiert zurückgegeben. Er ist nicht konfigurierbar.

UserIdentifiers steuert, welche AD-Attribute für die Suche per E-Mail, Telefon und Benutzername verwendet und als Benutzerkennungen auf oberster Ebene zurückgegeben werden können. Mindestens eines von Email, Phone oder Username muss konfiguriert und aus AD zurückgegeben werden, damit die Connector-Antwort gültig ist. Entfernen Sie eine Identifier-Zuordnung, wenn dieses Feld nicht für die Suche oder Rückgabe auf oberster Ebene verwendet werden soll. Dasselbe AD-Attribut kann weiterhin als Claim in Claims konfiguriert werden.

Wichtige Einstellungen:

• ApiKey: Gemeinsames Secret, mit dem FoxIDs sich beim Connector authentifiziert. FoxIDs sendet dies als HTTP Basic Authentication mit der API ID directory_connector. Verwenden Sie einen starken, eindeutigen Wert und speichern Sie ihn nach Möglichkeit als Umgebungsvariable oder IIS-Einstellung.
• ActiveDirectory:Domain: AD-Domänenname, z. B. example.local.
• ActiveDirectory:Server: Optionaler Domänencontroller oder LDAP-Endpoint. Wenn nicht gesetzt, wird Domain verwendet.
• ActiveDirectory:Port: LDAP-Port. Verwenden Sie 636 für LDAPS.
• ActiveDirectory:UseSsl: Aktiviert LDAPS. Lassen Sie dies für Kennwortoperationen aktiviert, sofern kein anderer sicherer Kanal garantiert ist.
• ActiveDirectory:Bind:Mode: Integrated verwendet die IIS Application Pool-Identität oder die Prozessidentität. ConfiguredCredentials verwendet das konfigurierte Username und Password.
• ActiveDirectory:Bind:Username und ActiveDirectory:Bind:Password: Credentials werden nur verwendet, wenn Mode auf ConfiguredCredentials gesetzt ist. Bevorzugen Sie für das Kennwort Umgebungsvariablen oder IIS-Konfiguration.
• ActiveDirectory:UserSearchBases: Ein oder mehrere Distinguished Names, in denen Benutzer gesucht werden, z. B. OU=Users,DC=example,DC=local.
• ActiveDirectory:GroupSearchBases: Ein oder mehrere Distinguished Names, in denen konfigurierte Rollengruppen gesucht werden.
• ActiveDirectory:UserIdentifiers: Optionale AD-Felder für Suche und Top-Level-Benutzerkennungen: Email, Phone und Username. Konfigurieren Sie mindestens eines.
• ActiveDirectory:Claims: Benutzerfelder, die als Claims zurückgegeben werden, z. B. name, given_name, family_name oder email.
• ActiveDirectory:GroupClaims: AD-Gruppenmitgliedschaften, die als Claims zurückgegeben werden, typischerweise role-Claims. Siehe Gruppenclaims für Konfigurationsdetails.

Gruppenclaims

Gruppenclaims sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie einen oder mehrere Einträge zu ActiveDirectory:GroupClaims hinzu.

Jeder GroupClaims Eintrag definiert den Claim-Typ, der zurückgegeben werden soll, und welche AD-Gruppenmitgliedschaften diesen Claim erzeugen sollen. Claim ist erforderlich und typischerweise role.

Es gibt drei typische Konfigurationen:

"GroupClaims": [
	{
		"Claim": "role",
		"IncludeNestedGroups": true,
		"ValueAttribute": "cn"
	},
	{
		"Claim": "role",
		"GroupDistinguishedName": "CN=Employees,OU=Groups,DC=example,DC=local",
		"IncludeNestedGroups": true,
		"Value": "employees"
	},
	{
		"Claim": "role",
		"GroupName": "Administrators",
		"IncludeNestedGroups": true,
		"ValueAttribute": "cn"
	}
]

Wenn weder GroupDistinguishedName noch GroupName konfiguriert ist, durchsucht der Connector die konfigurierten GroupSearchBases und gibt einen Claim für jede passende Gruppe zurück, deren Mitglied der Benutzer ist. In diesem Modus dürfen Sie Value nicht konfigurieren; der Claim-Wert muss aus ValueAttribute kommen. Mit dem Standard-ValueAttribute cn gibt eine Gruppe mit dem Namen admin_access Folgendes zurück:

{ "type": "role", "value": "admin_access" }

Verwenden Sie GroupDistinguishedName, wenn Sie den exakten DN der AD-Gruppe kennen. Dadurch vermeiden Sie eine Suche nach Namen und erhalten die präziseste Option.

Verwenden Sie GroupName, wenn der Connector eine einzelne Gruppe anhand ihres cn-Werts in GroupSearchBases finden soll. Die Suche muss genau eine Gruppe finden. Wenn mehr als eine Gruppe mit demselben cn in den konfigurierten GroupSearchBases vorhanden ist, schlägt die Anforderung fehl, weil die Gruppenzuordnung mehrdeutig ist.

Verwenden Sie Value nur, wenn GroupDistinguishedName oder GroupName konfiguriert ist und der zurückgegebene Claim einen festen Wert haben soll, der unabhängig vom Namen der AD-Gruppe ist. Beispielsweise kann eine Gruppe mit dem DN CN=Employees,OU=Groups,DC=example,DC=local den role-Wert employees zurückgeben.

Wenn Value nicht gesetzt ist, liest der Connector das konfigurierte ValueAttribute aus der gefundenen AD-Gruppe. Das Standard-ValueAttribute ist cn, wodurch der Name der AD-Gruppe als Claim-Wert zurückgegeben wird. Konfigurieren Sie nur dann ein anderes Gruppenattribut, wenn dieses Attribut im Gruppenobjekt vorhanden ist und den Wert enthält, der an FoxIDs gesendet werden soll.

IncludeNestedGroups steuert, wie die Mitgliedschaft geprüft wird:

• true verwendet die rekursive AD-Matching-Regel, sodass der Claim zurückgegeben wird, wenn der Benutzer direktes Mitglied ist oder über verschachtelte Gruppen Mitglied ist.
• false prüft nur die direkte Mitgliedschaft in der gefundenen Gruppe.

IIS-Installation

Die Komponente wird per Xcopy bereitgestellt. Sie hat keine Datenbank und keinen Installer. Aktualisierung oder Rollback erfolgen durch Ersetzen der Dateien im IIS-Website-Ordner, während die umgebungsspezifische Konfiguration erhalten bleibt.

1. Installieren Sie das ASP.NET Core Hosting Bundle für .NET 10 (direkter Download) auf dem Windows-Server.
2. Erstellen Sie einen Ordner, z. B. C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
3. Entpacken Sie die Release-Zip in diesen Ordner.
4. Konfigurieren Sie appsettings.json oder Umgebungsvariablen.
5. Erstellen Sie einen IIS Application Pool.
6. Setzen Sie die Application Pool-Identität auf ein Domänen-Servicekonto oder konfigurieren Sie Bind-Credentials in appsettings.json.
7. Erstellen Sie eine IIS-Site oder IIS-Application, die auf den Ordner zeigt.
8. Binden Sie die Site an HTTPS.
9. Erstellen Sie den Logordner C:\inetpub\logs\LogFiles\foxids-ad und gewähren Sie der Anwendungspoolidentität Schreibzugriff. Wenn der IIS-Anwendungspool z. B. FoxIDs.DirectoryConnector.AD heißt, gewähren Sie IIS AppPool\FoxIDs.DirectoryConnector.AD Schreibzugriff.
10. Prüfen Sie GET /health.

Verwenden Sie als FoxIDs API URL die base URL des Connectors, zum Beispiel:

https://connector.example.com

FoxIDs fügt authentication, change-password und set-password an diese base URL an.

TLS-Zertifikat

FoxIDs ruft den Connector über HTTPS auf, daher sollte die IIS-Site ein vertrauenswürdiges TLS-Zertifikat haben. Sie können ein eigenes Zertifikat verwenden oder optional mit win-acme ein kostenloses Let's Encrypt-Zertifikat erstellen.

Mit win-acme laden Sie das neueste Release win-acme.v2.x.x.x64.pluggable.zip herunter, entpacken es in einen dauerhaften Ordner, führen wacs.exe aus einer erhöhten Command Prompt aus und wählen die IIS-Site aus, die den Directory Connector hostet. Win-acme fügt die HTTPS-Bindung hinzu und registriert die automatische Zertifikatserneuerung in der Windows Task Scheduler.

Den vollständigen Ablauf finden Sie im FoxIDs Windows / IIS HTTP and HTTPS guide.

FoxIDs-Umgebungskonfiguration

Nachdem der Connector installiert und über HTTPS erreichbar ist, aktivieren Sie ihn in der FoxIDs-Umgebung:

1. Öffnen Sie den FoxIDs Control Client.
2. Wählen Sie den Tenant und die Umgebung aus, die den Connector verwenden sollen.
3. Gehen Sie zu Settings > Environment.
4. Suchen Sie Directory connector settings.
5. Aktivieren Sie den directory connector.
6. Geben Sie die API URL des Connectors ein, z. B. https://connector.example.com.
7. Geben Sie dasselbe Secret wie ApiKey des Connectors ein.
8. Wählen Sie, ob FoxIDs eine lokale Kennwortkopie speichern soll und ob die FoxIDs-Kennwortrichtlinie vor dem Connector-Aufruf angewendet werden soll.

Wenn die FoxIDs-Kennwortrichtlinie aktiviert ist, validiert FoxIDs Kennwortlänge, Komplexität und Kennworthistorie vor dem Aufruf des Connectors. Dadurch erhalten Benutzer sofortiges FoxIDs-Policy-Feedback, aber AD bleibt maßgeblich und kann ein Kennwort weiterhin mit password_not_accepted ablehnen, aufgrund von Mindestlänge, Komplexität, Kennworthistorie, minimum password age, fine-grained password policy oder einem custom password filter.

Die API URL in FoxIDs muss auf die base URL des Connectors zeigen. FoxIDs fügt beim Aufruf des Connectors die Endpunktnamen hinzu.

Standardmäßig ist in der Login authentication method nur die Anmeldung mit E-Mail-Adresse aktiviert. Wenn Benutzer sich mit Benutzername oder Telefonnummer anmelden sollen, aktivieren Sie die entsprechenden Benutzeridentifikatoren in der Login authentication method.

Im folgenden Beispiel sind sowohl Benutzername als auch E-Mail aktiviert.

Patching und Updates

1. Laden Sie das neue Release FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip herunter und lesen Sie die Release Notes.
2. Entpacken Sie die Zip-Datei in einen temporären Ordner und kopieren Sie die aktuellen appsettings*.json Dateien hinein, oder belassen Sie Secrets in IIS-Umgebungsvariablen.
3. Stoppen Sie die IIS-Site oder den Application Pool.
4. Benennen Sie den aktuellen Ordner um oder kopieren Sie ihn in einen Backup-Ordner, z. B. C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
5. Kopieren Sie die neuen Dateien per Xcopy nach C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory und prüfen Sie die NTFS-Berechtigungen für die Application Pool-Identität.
6. Starten Sie den Application Pool und prüfen Sie GET /health. Testen Sie anschließend eine Directory Connector-Anmeldung oder eine Kennwortoperation.
7. Wenn ein Rollback erforderlich ist, stoppen Sie den Application Pool, stellen Sie den Backup-Ordner am Live-Pfad wieder her und starten Sie den Application Pool erneut.

Die Standard-web.config schreibt ASP.NET Core-stdout-Logs nach C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Lassen Sie stdout-Logging aktiviert, bis der Connector verifiziert ist, und erwägen Sie danach, es zu deaktivieren oder die Logs nach der Produktionsvalidierung an das normale Logsystem der Umgebung weiterzuleiten.

Verwandte Dokumentation

• Directory Connector
• Interne Benutzer
• FoxIDs Deployment unter Windows / IIS