Active Directory Directory Connector

Active Directory Directory Connector is een FoxIDs-component die de Directory Connector-API implementeert voor één AD/LDAP-domein.

Installeer de component in de Windows-omgeving van de klant, waar deze de domeincontrollers kan bereiken. FoxIDs roept de component aan via HTTPS, en de component valideert gebruikers, wijzigt wachtwoorden, zet wachtwoorden en retourneert gebruikerseigenschappen en claims uit Active Directory.

De connector wordt geïnstalleerd en geconfigureerd op de Windows/IIS-server dicht bij Active Directory. In FoxIDs wordt de connector daarna ingeschakeld op de FoxIDs-omgeving onder Settings > Environment > Directory connector settings, waar de API URL en secret van de connector worden geconfigureerd.

De component wordt uitgebracht als een Windows-zip samen met FoxIDs-releases:

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

Endpoints

De component stelt beschikbaar:

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

Het /health endpoint is niet geauthenticeerd en retourneert alleen minimale status. Het controleert vereiste configuratie, AD-bind, toegang tot user search-base en optionele toegang tot group search-base. Het test geen gedelegeerde rechten voor set-password / password reset. Gedetailleerde fouten en stack traces worden op de server gelogd en niet door het endpoint geretourneerd.

Voorbeeldrespons:

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

De response bevat alleen status, adBind, userSearch en groupSearch. status is alleen ok wanneer vereiste configuratie geldig is, AD-bind slaagt, toegang tot user search-base slaagt en toegang tot group search-base niet is mislukt. groupSearch is not_configured wanneer geen group search base is geconfigureerd. Als een controle niet kan worden uitgevoerd omdat een eerdere controle is mislukt of configuratie ontbreekt, wordt het veld geretourneerd als unknown.

Vereisten

Windows Server met IIS.
ASP.NET Core Hosting Bundle voor .NET 10.
Netwerktoegang vanaf de IIS-server naar de geconfigureerde domeincontroller.
LDAPS of een ander veilig kanaal voor wachtwoordoperaties.
Eén AD-domein per connector-deployment.
Een domeinserviceaccount als geconfigureerde credentials worden gebruikt.
Gedelegeerde AD-rechten voor password reset als set-password ondersteund moet worden.

Een domein-joined IIS-server waarvan de application pool draait als domeinserviceaccount is de aanbevolen configuratie. Geconfigureerde bind-credentials worden ook ondersteund via appsettings.json of omgevingsvariabelen.

Authenticatie

Configureer een sterke API-sleutel in appsettings.json. FoxIDs verzendt HTTP Basic authentication met API ID directory_connector en de geconfigureerde secret.

Gebruik de header X-FoxIDs-Api-Key: <api-key> alleen als een reverse proxy vóór Directory Connector Basic authentication afhandelt voordat het verzoek de component bereikt en api-key herschrijft.

AD lookup en binding

De component zoekt eerst in AD met de geconfigureerde service-identiteit. Lookup wordt ondersteund op:

e-mail
telefoon
gebruikersnaam
directoryUserId wanneer FoxIDs deze al kent

De gebruiker wordt in FoxIDs geïdentificeerd met de AD objectGUID, gecodeerd als base64. De waarde wordt teruggegeven als directoryUserId en blijft stabiel wanneer e-mail, telefoon of gebruikersnaam verandert.

Voor wachtwoordauthenticatie vindt de component de distinguished name van de gebruiker en bindt daarna aan AD als die gebruiker met het opgegeven wachtwoord. Dit voorkomt dubbelzinnige gebruikerslookup en ondersteunt alle geconfigureerde identificatortypen.

Voor het wijzigen van een wachtwoord valideert AD het huidige wachtwoord en het wachtwoordbeleid.

Als het FoxIDs-wachtwoordbeleid is ingeschakeld voor Directory Connector, valideert FoxIDs wachtwoordlengte, complexiteit en wachtwoordgeschiedenis vooraf voordat de connector wordt aangeroepen. Dit geeft de gebruiker preciezere feedback voor deze controles. AD blijft leidend en kan het wachtwoord daarna nog steeds afwijzen met password_not_accepted, bijvoorbeeld vanwege minimale wachtwoordlengte, complexiteit, wachtwoordgeschiedenis, minimum password age, fine-grained password policy of een custom password filter.

Voor set-password moet de geconfigureerde service-identiteit gedelegeerde reset-password-rechten hebben.

Toegang voor AD-serviceaccount

De connector moet draaien met een dedicated AD-service-identiteit. Maak deze identiteit geen domeinadministrator. Gebruik een normale domeingebruiker of een aangepaste beveiligingsgroep, en delegeer alleen de noodzakelijke rechten op de OU's die de connector gebruikt.

Voor gebruikerslookup en authenticatie moet de connector-identiteit in elke geconfigureerde UserSearchBases OU mogen zoeken en de gebruikersobjecten en attributen kunnen lezen die door de connector worden gebruikt. Een nieuwe dedicated AD-service-identiteit heeft deze leestoegang vaak al standaard, tenzij de AD-ACL's zijn beperkt.

Voor wachtwoordauthenticatie vindt de connector eerst de gebruiker met de service-identiteit en bindt daarna aan AD als de gebruiker met het opgegeven wachtwoord. Dit vereist niet dat de service-identiteit het wachtwoord van de gebruiker kent of reset.

Voor het wijzigen van een wachtwoord, waarbij de gebruiker het huidige wachtwoord opgeeft, gebruikt de connector het AD password change-gedrag en valideert AD het huidige wachtwoord en het wachtwoordbeleid.

Voor set-password / password reset moeten password reset-rechten worden gedelegeerd op de gebruikersobjecten in elke geconfigureerde UserSearchBases OU waar de connector password reset moet ondersteunen. Klik in Active Directory Users and Computers met de rechtermuisknop op de user OU die door de connector wordt gebruikt, selecteer Delegate Control..., selecteer de connector-identiteit en selecteer in de stap Tasks to Delegate Reset user passwords and force password change at next logon.

Delegeer de Reset user passwords and force password change at next logon-rechten aan de connector-identiteit

Delegeer ook eventuele aanvullende wachtwoordgerelateerde rechten die door het domeinbeleid worden vereist, alleen als de omgeving die handelingen gebruikt. Voor groepsrol-claims heeft de connector-identiteit leestoegang nodig tot de geconfigureerde GroupSearchBases. Deze moet de group OU kunnen weergeven en groepsattributen zoals cn, distinguishedName en member kunnen lezen.

Configuratie

Configuratie gebruikt standaard .NET-configuratie. Waarden kunnen worden ingesteld in appsettings.json, omgevingsvariabelen, IIS-configuratie of een andere .NET-configuratieprovider.

Voorbeeld:

{
	"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 wordt altijd toegewezen vanuit de AD-objectGUID en base64-gecodeerd geretourneerd. Deze is niet configureerbaar.

UserIdentifiers bepaalt welke AD-attributen kunnen worden gebruikt voor lookup via e-mail, telefoon en gebruikersnaam en als top-level gebruikersidentificaties worden geretourneerd. Minimaal een van Email, Phone of Username moet zijn geconfigureerd en door AD worden geretourneerd voor een geldige connectorrespons. Verwijder een identifier-mapping als dat veld niet voor lookup of retour op topniveau moet worden gebruikt. Hetzelfde AD-attribuut kan nog steeds als claim in Claims worden geconfigureerd.

Belangrijke instellingen:

ApiKey: gedeelde secret waarmee FoxIDs zich bij de connector authenticeert. FoxIDs verzendt dit als HTTP Basic authentication met API ID directory_connector. Gebruik een sterke unieke waarde en sla deze waar mogelijk op als omgevingsvariabele of IIS-instelling.
ActiveDirectory:Domain: AD-domeinnaam, bijvoorbeeld example.local.
ActiveDirectory:Server: optionele domeincontroller of LDAP-endpoint. Als deze ontbreekt, wordt Domain gebruikt.
ActiveDirectory:Port: LDAP-poort. Gebruik 636 voor LDAPS.
ActiveDirectory:UseSsl: schakelt LDAPS in. Laat dit ingeschakeld voor wachtwoordoperaties, tenzij een ander beveiligd kanaal gegarandeerd is.
ActiveDirectory:Bind:Mode: Integrated gebruikt de IIS application pool-identiteit of procesidentiteit. ConfiguredCredentials gebruikt de geconfigureerde Username en Password.
ActiveDirectory:Bind:Username en ActiveDirectory:Bind:Password: credentials worden alleen gebruikt wanneer Mode ConfiguredCredentials is. Geef voor het wachtwoord de voorkeur aan omgevingsvariabelen of IIS-configuratie.
ActiveDirectory:UserSearchBases: een of meer distinguished names waarin gebruikers worden gezocht, bijvoorbeeld OU=Users,DC=example,DC=local.
ActiveDirectory:GroupSearchBases: een of meer distinguished names waarin geconfigureerde rolgroepen worden gezocht.
ActiveDirectory:UserIdentifiers: optionele AD-velden voor lookup en top-level gebruikersidentificaties: Email, Phone en Username. Configureer er minstens een.
ActiveDirectory:Claims: gebruikersvelden die als claims worden geretourneerd, bijvoorbeeld name, given_name, family_name of email.
ActiveDirectory:GroupClaims: AD-groepslidmaatschappen die als claims worden geretourneerd, meestal role-claims. Zie Groepsclaims voor configuratiedetails.

Groepsclaims

Groepsclaims zijn standaard uitgeschakeld. Om ze in te schakelen, voegt u een of meer items toe aan ActiveDirectory:GroupClaims.

Elke GroupClaims-vermelding definieert het claimtype dat moet worden geretourneerd en welke AD-groepslidmaatschappen dat claim moeten opleveren. Claim is verplicht en is meestal role.

Er zijn drie veelvoorkomende configuraties:

"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"
	}
]

Als noch GroupDistinguishedName noch GroupName is geconfigureerd, doorzoekt de connector de geconfigureerde GroupSearchBases en retourneert één claim voor elke overeenkomende groep waarvan de gebruiker lid is. In deze modus mag u Value niet configureren; de claimwaarde moet afkomstig zijn van ValueAttribute. Met de standaard-ValueAttribute cn retourneert een groep met de naam admin_access:

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

Gebruik GroupDistinguishedName wanneer u de exacte DN van de AD-groep kent. Dit voorkomt zoeken op naam en is de meest precieze optie.

Gebruik GroupName wanneer de connector één enkele groep moet vinden op basis van de cn-waarde in GroupSearchBases. De zoekopdracht moet exact één groep vinden. Als meer dan één groep met dezelfde cn in de geconfigureerde GroupSearchBases bestaat, mislukt het verzoek omdat de groepsmapping dubbelzinnig is.

Gebruik Value alleen wanneer GroupDistinguishedName of GroupName is geconfigureerd en de geretourneerde claim een vaste waarde moet hebben die onafhankelijk is van de naam van de AD-groep. Een groep met de DN CN=Employees,OU=Groups,DC=example,DC=local kan bijvoorbeeld de role-waarde employees retourneren.

Als Value niet is ingesteld, leest de connector de geconfigureerde ValueAttribute uit de gevonden AD-groep. De standaard-ValueAttribute is cn, waarmee de naam van de AD-groep als claimwaarde wordt geretourneerd. Configureer alleen een ander groepsattribuut als dat attribuut op het groepsobject bestaat en de waarde bevat die naar FoxIDs moet worden verzonden.

IncludeNestedGroups bepaalt hoe lidmaatschap wordt gecontroleerd:

true gebruikt de recursieve AD-matchingregel, zodat de claim wordt geretourneerd als de gebruiker direct lid is of via geneste groepen lid is.
false controleert alleen direct lidmaatschap van de gevonden groep.

IIS-installatie

De component wordt gedeployed met Xcopy. Er is geen database en geen installer. Updaten of terugdraaien gebeurt door de bestanden in de map van de IIS-website te vervangen terwijl de omgevingsspecifieke configuratie behouden blijft.

Installeer ASP.NET Core Hosting Bundle voor .NET 10 (directe download) op de Windows-server.
Maak een map, bijvoorbeeld C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
Pak de release-zip uit in de map.
Configureer appsettings.json of omgevingsvariabelen.
Maak een IIS application pool.
Stel de application pool-identiteit in op een domeinserviceaccount, of configureer bind-credentials in appsettings.json.
Maak een IIS-site of IIS-application die naar de map wijst.
Bind de site aan HTTPS.
Maak de logmap C:\inetpub\logs\LogFiles\foxids-ad en geef de application pool-identiteit schrijftoegang. Als de IIS-application pool bijvoorbeeld FoxIDs.DirectoryConnector.AD heet, geef dan schrijftoegang aan IIS AppPool\FoxIDs.DirectoryConnector.AD.
Controleer GET /health.

Gebruik als FoxIDs API URL de base URL van de connector, bijvoorbeeld:

https://connector.example.com

FoxIDs voegt authentication, change-password en set-password toe aan die base URL.

TLS-certificaat

FoxIDs roept de connector aan via HTTPS, dus de IIS-site moet een vertrouwd TLS-certificaat hebben. U kunt uw eigen certificaat gebruiken of optioneel een gratis Let's Encrypt-certificaat maken met win-acme.

Met win-acme downloadt u de nieuwste release win-acme.v2.x.x.x64.pluggable.zip, pakt u deze uit naar een permanente map, voert u wacs.exe uit vanuit een verhoogde Command Prompt en selecteert u de IIS-site die Directory Connector host. Win-acme voegt de HTTPS-binding toe en registreert automatische certificaatvernieuwing in Windows Task Scheduler.

Zie de volledige flow in de FoxIDs Windows / IIS HTTP and HTTPS guide.

FoxIDs-omgevingsconfiguratie

Wanneer de connector is geïnstalleerd en bereikbaar is via HTTPS, schakelt u deze in de FoxIDs-omgeving in:

Open FoxIDs Control Client.
Selecteer de tenant en omgeving die de connector moeten gebruiken.
Ga naar Settings > Environment.
Zoek Directory connector settings.
Schakel directory connector in.
Voer de API URL van de connector in, bijvoorbeeld https://connector.example.com.
Voer dezelfde secret in als de ApiKey van de connector.
Kies of FoxIDs een lokale wachtwoordkopie moet opslaan en of het FoxIDs-wachtwoordbeleid moet worden toegepast vóór de connector-aanroep.

Wanneer het FoxIDs-wachtwoordbeleid is ingeschakeld, valideert FoxIDs wachtwoordlengte, complexiteit en wachtwoordgeschiedenis voordat de connector wordt aangeroepen. Dit geeft gebruikers directe FoxIDs policy-feedback, maar AD blijft leidend en kan een wachtwoord nog steeds afwijzen met password_not_accepted vanwege minimale wachtwoordlengte, complexiteit, wachtwoordgeschiedenis, minimum password age, fine-grained password policy of een custom password filter.

FoxIDs Directory Connector-instellingen voor Active Directory

De API URL in FoxIDs moet naar de base URL van de connector wijzen. FoxIDs voegt de endpointnamen toe wanneer de connector wordt aangeroepen.

Standaard is in Login authentication method alleen aanmelden met e-mailadres ingeschakeld. Als gebruikers zich moeten kunnen aanmelden met gebruikersnaam of telefoonnummer, schakel dan de bijbehorende gebruikersidentificatoren in Login authentication method in.

In het onderstaande voorbeeld zijn zowel gebruikersnaam als e-mail ingeschakeld.

FoxIDs Login authentication method-gebruikersidentificatoren voor Directory Connector

Patching en updates

Download de nieuwe release FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip en lees de release notes.
Pak de zip uit naar een tijdelijke map en kopieer de huidige appsettings*.json bestanden mee, of bewaar secrets in IIS-omgevingsvariabelen.
Stop de IIS-site of application pool.
Hernoem of kopieer de huidige map naar een back-upmap, bijvoorbeeld C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
Kopieer de nieuwe bestanden met Xcopy naar C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory en controleer de NTFS-rechten voor de application pool-identiteit.
Start de application pool en controleer GET /health, en test daarna een Directory Connector-aanmelding of een wachtwoordbewerking.
Als een rollback nodig is, stop dan de application pool, herstel de back-upmap naar het live-pad en start de application pool opnieuw.

De standaard-web.config schrijft ASP.NET Core-stdout-logs naar C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Laat stdout-logging ingeschakeld totdat de connector is geverifieerd en overweeg daarna om deze uit te schakelen of de logs door te sturen naar het normale logsysteem van de omgeving na productievalidatie.