Active Directory Directory Connector

Active Directory Directory Connector er en FoxIDs-komponent, der implementerer Directory Connector API'et for et AD/LDAP-domæne.

Installer komponenten i kundens Windows-miljø, hvor den kan nå domænecontrollere. FoxIDs kalder komponenten over HTTPS, og komponenten validerer brugere, ændrer adgangskoder, sætter adgangskoder og returnerer brugeregenskaber og claims fra Active Directory.

Connectoren installeres og konfigureres på Windows/IIS-serveren tæt på Active Directory. I FoxIDs aktiveres den derefter på miljøet under Settings > Environment > Directory connector settings, hvor connectorens API URL og secret konfigureres.

Komponenten udgives som en Windows-zip sammen med FoxIDs-udgivelser:

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

Endpoints

Komponenten eksponerer:

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

/health endpointet er ikke autentificeret og returnerer kun minimal status. Det kontrollerer krævet konfiguration, AD-bind, læseadgang til user search-base og valgfri læseadgang til group search-base. Det tester ikke delegerede set-password / reset-password-rettigheder. Detaljerede fejl og stack traces logges på serveren og returneres ikke af endpointet.

Eksempel på svar:

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

Svaret indeholder kun status, adBind, userSearch og groupSearch. status er kun ok, når krævet konfiguration er gyldig, AD-bind lykkes, læseadgang til user search-base lykkes, og group search-base adgang ikke er fejlet. groupSearch er not_configured, når der ikke er konfigureret nogen group search base. Hvis et check ikke kan udføres, fordi et tidligere check fejlede eller konfiguration mangler, returneres feltet som unknown.

Krav

Windows Server med IIS.
ASP.NET Core Hosting Bundle til .NET 10.
Netværksadgang fra IIS-serveren til den konfigurerede domænecontroller.
LDAPS eller en anden sikker kanal til adgangskodeoperationer.
Ét AD-domæne pr. connector-deployment.
En domæneservicekonto, hvis konfigurerede credentials bruges.
Delegeret AD password reset-rettighed, hvis set-password skal understøttes.

En domænejoinet IIS-server, hvor application pool kører som en domæneservicekonto, er den anbefalede opsætning. Konfigurerede bind-credentials understøttes også via appsettings.json eller miljøvariabler.

Autentificering

Konfigurer en stærk API-nøgle i appsettings.json. FoxIDs sender HTTP Basic authentication med API ID directory_connector og den konfigurerede secret.

Brug kun X-FoxIDs-Api-Key: <api-key> headeren, hvis en reverse proxy foran Directory Connector håndterer Basic authentication, før anmodningen når komponenten, og omskriver api-key.

AD-opslag og binding

Komponenten søger først i AD med den konfigurerede serviceidentitet. Den understøtter opslag efter:

e-mail
telefon
brugernavn
directoryUserId, når FoxIDs allerede kender det

Brugeren identificeres i FoxIDs med AD objectGUID kodet som base64. Værdien returneres som directoryUserId og forbliver stabil, hvis e-mail, telefon eller brugernavn ændrer sig.

Ved adgangskodeautentificering finder komponenten brugerens distinguished name og binder derefter til AD som den bruger med den indsendte adgangskode. Det undgår tvetydigt brugeropslag og understøtter alle konfigurerede identifikatortyper.

Ved ændring af adgangskode validerer AD den nuværende adgangskode og adgangskodepolitikken.

Hvis FoxIDs adgangskodepolitik er aktiveret for Directory Connector, pre-validerer FoxIDs adgangskodelængde, kompleksitet og adgangskodehistorik, før connectoren kaldes. Det giver brugeren mere præcis feedback for disse checks. AD er stadig autoritativt og kan fortsat afvise adgangskoden bagefter med password_not_accepted, f.eks. på grund af minimumslængde, kompleksitet, adgangskodehistorik, minimum password age, fine-grained password policy eller et custom password filter.

Ved set-password skal den konfigurerede serviceidentitet have delegerede reset-password-rettigheder.

AD-servicekontoens adgang

Connectoren bør køre med en dedikeret AD-serviceidentitet. Gør ikke identiteten til domæneadministrator. Brug en almindelig domænebruger eller en brugerdefineret sikkerhedsgruppe, og delegér kun de nødvendige rettigheder på de OU'er, connectoren bruger.

Til brugeropslag og autentificering skal connector-identiteten have tilladelse til at søge i hver konfigureret UserSearchBases OU og læse de brugerobjekter og attributter, som connectoren bruger. En ny dedikeret AD-serviceidentitet har ofte allerede denne læseadgang som standard, medmindre AD ACL'erne er blevet begrænset.

Ved adgangskodeautentificering finder connectoren først brugeren med serviceidentiteten og binder derefter til AD som brugeren med den indsendte adgangskode. Det kræver ikke, at serviceidentiteten kender eller nulstiller brugerens adgangskode.

Ved ændring af adgangskode, hvor brugeren angiver den nuværende adgangskode, bruger connectoren AD's password change-adfærd, og AD validerer den nuværende adgangskode og adgangskodepolitikken.

Til set-password / password reset skal der delegeres password reset-rettigheder på brugerobjekterne i hver konfigureret UserSearchBases OU, hvor connectoren skal understøtte password reset. I Active Directory Users and Computers skal du højreklikke på den user OU, connectoren bruger, vælge Delegate Control..., vælge connector-identiteten og på trinnet Tasks to Delegate vælge Reset user passwords and force password change at next logon.

Delegér Reset user passwords and force password change at next logon-rettigheden til connector-identiteten

Delegér også eventuelle yderligere password-relaterede rettigheder, som domænepolitikken kræver, kun hvis miljøet bruger de handlinger. Til grupperolle-claims skal connector-identiteten have læseadgang til de konfigurerede GroupSearchBases. Den skal kunne liste group OU'en og læse gruppeattributter som cn, distinguishedName og member.

Konfiguration

Konfiguration bruger standard .NET-konfiguration. Værdier kan angives i appsettings.json, miljøvariabler, IIS-konfiguration eller en anden .NET-konfigurationsprovider.

Eksempel:

{
	"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 mappes altid fra AD objectGUID og returneres base64-kodet. Den kan ikke konfigureres.

UserIdentifiers styrer, hvilke AD-attributter der kan bruges til opslag via e-mail, telefon og brugernavn og returneres som brugeridentifikatorer på topniveau. Mindst en af Email, Phone eller Username skal være konfigureret og returneret fra AD for at give et gyldigt connectorsvar. Fjern en identifier-mapping, hvis feltet ikke skal bruges til opslag eller returneres på topniveau. Den samme AD-attribut kan stadig konfigureres som et claim i Claims.

Vigtige indstillinger:

ApiKey: Delt secret, som FoxIDs bruger til at autentificere mod connectoren. FoxIDs sender den som HTTP Basic authentication med API ID directory_connector. Brug en stærk, unik værdi, og gem den som miljøvariabel eller IIS-indstilling, hvor det er muligt.
ActiveDirectory:Domain: AD-domænenavnet, der bruges ved forbindelse til domænet, f.eks. example.local.
ActiveDirectory:Server: Valgfri domænecontroller eller LDAP-endpoint. Hvis den udelades, bruges Domain.
ActiveDirectory:Port: LDAP-port. Brug 636 til LDAPS.
ActiveDirectory:UseSsl: Aktiverer LDAPS. Behold den aktiveret til adgangskodeoperationer, medmindre en anden sikker kanal er garanteret.
ActiveDirectory:Bind:Mode: Integrated bruger IIS application pool-identiteten eller procesidentiteten. ConfiguredCredentials bruger de konfigurerede Username og Password.
ActiveDirectory:Bind:Username og ActiveDirectory:Bind:Password: Credentials bruges kun, når Mode er ConfiguredCredentials. Foretræk miljøvariabler eller IIS-konfiguration til adgangskoden.
ActiveDirectory:UserSearchBases: Et eller flere distinguished names, hvor brugere søges, f.eks. OU=Users,DC=example,DC=local.
ActiveDirectory:GroupSearchBases: Et eller flere distinguished names, hvor konfigurerede rollegrupper søges.
ActiveDirectory:UserIdentifiers: Valgfrie AD-felter til opslag og topniveau brugeridentifikatorer: Email, Phone og Username. Konfigurer mindst et.
ActiveDirectory:Claims: Brugerfelter, der returneres som claims, f.eks. name, given_name, family_name eller email.
ActiveDirectory:GroupClaims: AD-gruppemedlemskaber, der returneres som claims, typisk role-claims. Se Gruppeclaims for konfigurationsdetaljer.

Gruppeclaims

Gruppeclaims er deaktiveret som standard. For at aktivere dem skal du tilføje en eller flere poster til ActiveDirectory:GroupClaims.

Hver GroupClaims post definerer claim-typen, der skal returneres, og hvilke AD-gruppemedlemskaber der skal producere dette claim. Claim er påkrævet og er typisk role.

Der er tre almindelige konfigurationer:

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

Hvis hverken GroupDistinguishedName eller GroupName er konfigureret, søger connectoren i de konfigurerede GroupSearchBases og returnerer ét claim for hver matchende gruppe, som brugeren er medlem af. I denne tilstand må du ikke konfigurere Value; claim-værdien skal komme fra ValueAttribute. Med standard ValueAttribute på cn returnerer en gruppe med navnet admin_access:

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

Brug GroupDistinguishedName, når du kender den præcise AD-gruppes DN. Det undgår søgning efter navn og er den mest præcise mulighed.

Brug GroupName, når connectoren skal finde en enkelt gruppe ud fra dens cn-værdi i GroupSearchBases. Søgningen skal matche præcis én gruppe. Hvis mere end én gruppe med samme cn findes i de konfigurerede GroupSearchBases, mislykkes anmodningen, fordi gruppemappingen er tvetydig.

Brug kun Value, når GroupDistinguishedName eller GroupName er konfigureret, og det returnerede claim skal have en fast værdi, som er uafhængig af AD-gruppens navn. For eksempel kan en gruppe med DN CN=Employees,OU=Groups,DC=example,DC=local returnere role-værdien employees.

Hvis Value ikke er sat, læser connectoren den konfigurerede ValueAttribute fra den matchede AD-gruppe. Standard ValueAttribute er cn, hvilket returnerer AD-gruppens navn som claim-værdi. Konfigurer kun en anden gruppeattribut, hvis attributten findes på gruppeobjektet og indeholder den værdi, der skal sendes til FoxIDs.

IncludeNestedGroups styrer, hvordan medlemskab kontrolleres:

true bruger AD's rekursive matchningsregel, så claimet returneres, hvis brugeren er direkte medlem eller er medlem gennem nested grupper.
false kontrollerer kun direkte medlemskab i den matchede gruppe.

IIS-installation

Komponenten deployes med Xcopy. Den har ingen database og ingen installer. Opdatering eller rollback udføres ved at erstatte filerne i IIS-websitets mappe, mens den miljøspecifikke konfiguration bevares.

Installer ASP.NET Core Hosting Bundle for .NET 10 (direkte download) på Windows-serveren.
Opret en mappe, f.eks. C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
Udpak release-zippen til mappen.
Konfigurer appsettings.json eller miljøvariabler.
Opret en IIS application pool.
Sæt application pool-identiteten til en domæneservicekonto, eller konfigurer bind-credentials i appsettings.json.
Opret et IIS-site eller en IIS-application, der peger på mappen.
Bind sitet til HTTPS.
Opret logmappen C:\inetpub\logs\LogFiles\foxids-ad, og giv application pool-identiteten skriveadgang. Hvis IIS-application poolen f.eks. hedder FoxIDs.DirectoryConnector.AD, skal du give skriveadgang til IIS AppPool\FoxIDs.DirectoryConnector.AD.
Verificer GET /health.

For en FoxIDs API URL skal du bruge connectorens base URL, f.eks.:

https://connector.example.com

FoxIDs tilføjer authentication, change-password og set-password til den base URL.

TLS-certifikat

FoxIDs kalder connectoren over HTTPS, så IIS-sitet bør have et betroet TLS-certifikat. Du kan bruge dit eget certifikat eller valgfrit oprette et gratis Let's Encrypt-certifikat med win-acme.

Med win-acme downloader du den seneste win-acme.v2.x.x.x64.pluggable.zip release, udpakker den til en permanent mappe, kører wacs.exe fra en forhøjet Command Prompt og vælger IIS-sitet, der hoster Directory Connector. Win-acme tilføjer HTTPS-bindingen og registrerer automatisk certifikatfornyelse i Windows Task Scheduler.

Se den fulde win-acme-proces i FoxIDs Windows / IIS HTTP and HTTPS guide.

FoxIDs-miljøkonfiguration

Når connectoren er installeret og kan nås over HTTPS, aktiveres den i FoxIDs-miljøet:

Åbn FoxIDs Control Client.
Vælg den tenant og det miljø, der skal bruge connectoren.
Gå til Settings > Environment.
Find Directory connector settings.
Aktivér directory connector.
Angiv connectorens API URL, f.eks. https://connector.example.com.
Angiv samme secret som connectorens ApiKey.
Vælg, om FoxIDs skal gemme en lokal adgangskodekopi, og om FoxIDs adgangskodepolitik skal anvendes før connector-kaldet.

Når FoxIDs adgangskodepolitik er aktiveret, validerer FoxIDs adgangskodelængde, kompleksitet og adgangskodehistorik, før connectoren kaldes. Det giver brugerne øjeblikkelig FoxIDs policy-feedback, men AD er stadig autoritativt og kan fortsat afvise en adgangskode med password_not_accepted på grund af minimumslængde, kompleksitet, adgangskodehistorik, minimum password age, fine-grained password policy eller et custom password filter.

FoxIDs Directory Connector-indstillinger for Active Directory

API URL'en i FoxIDs skal pege på connectorens base URL. FoxIDs tilføjer endpoint-navnene, når den kalder connectoren.

Som standard er det kun login med e-mailadresse, der er aktiveret i Login authentication method. Hvis brugerne skal kunne logge ind med brugernavn eller telefonnummer, skal de tilsvarende brugeridentifikatorer aktiveres i Login authentication method.

Eksemplet nedenfor har både brugernavn og e-mail aktiveret.

FoxIDs Login authentication method-brugeridentifikatorer til Directory Connector

Patching og opdateringer

Download den nye FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip release, og læs release notes.
Udpak zip-filen til en midlertidig mappe, og kopier de nuværende appsettings*.json filer over, eller behold secrets i IIS-miljøvariabler.
Stop IIS-sitet eller application poolen.
Omdøb eller kopier den nuværende mappe til en backupmappe, f.eks. C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
Xcopy de nye filer ind i C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory, og verificer NTFS-rettigheder for application pool-identiteten.
Start application poolen, og verificer GET /health, og test derefter et Directory Connector-login eller en adgangskodeoperation.
Hvis rollback er nødvendig, skal du stoppe application poolen, gendanne backupmappen til live-stien og starte application poolen igen.

Standard-web.config skriver ASP.NET Core stdout-logs til C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Behold stdout-logging aktiveret, indtil connectoren er verificeret, og overvej derefter at deaktivere den eller videresende loggene til miljøets normale logsystem efter validering i produktion.