Active Directory Directory Connector

Active Directory Directory Connector er en FoxIDs-komponent som implementerer Directory Connector-API-et for ett AD/LDAP-domene.

Installer komponenten i kundens Windows-miljø der den kan nå domenekontrollerne. FoxIDs kaller komponenten over HTTPS, og komponenten validerer brukere, endrer passord, setter passord og returnerer brukeregenskaper og claims fra Active Directory.

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

Komponenten utgis som en Windows-zip sammen med FoxIDs-utgivelser:

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

Endpoints

Komponenten eksponerer:

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

/health endpointet er ikke autentisert og returnerer bare minimal status. Det kontrollerer nødvendig konfigurasjon, AD-bind, tilgang til user search-base og valgfri tilgang til group search-base. Det tester ikke delegerte rettigheter for set-password / password reset. Detaljerte feil og stack traces logges på serveren og returneres ikke av endepunktet.

Eksempel på svar:

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

Svaret inneholder bare status, adBind, userSearch og groupSearch. status er ok bare når nødvendig konfigurasjon er gyldig, AD-bind lykkes, tilgang til user search-base lykkes, og group search-base tilgang ikke har feilet. groupSearch er not_configured når ingen group search base er konfigurert. Hvis en sjekk ikke kan utføres fordi en tidligere sjekk har feilet eller konfigurasjon mangler, returneres feltet som unknown.

Krav

  • Windows Server med IIS.
  • ASP.NET Core Hosting Bundle for .NET 10.
  • Nettverkstilgang fra IIS-serveren til den konfigurerte domenekontrolleren.
  • LDAPS eller en annen sikker kanal for passordoperasjoner.
  • Ett AD-domene per connector-deployment.
  • En domeneservicekonto hvis konfigurerte credentials brukes.
  • Delegert AD password reset-rettighet hvis set-password skal støttes.

En domenejoinet IIS-server som kjører application pool som en domeneservicekonto, er anbefalt oppsett. Konfigurerte bind-credentials støttes også via appsettings.json eller miljøvariabler.

Autentisering

Konfigurer en sterk API-nøkkel i appsettings.json. FoxIDs sender HTTP Basic authentication med API ID directory_connector og den konfigurerte secreten.

Bruk bare headeren X-FoxIDs-Api-Key: <api-key> hvis en reverse proxy foran Directory Connector håndterer Basic authentication før forespørselen når komponenten og omskriver api-key.

AD-oppslag og binding

Komponenten søker først i AD med den konfigurerte serviceidentiteten. Den støtter oppslag etter:

  • e-post
  • telefon
  • brukernavn
  • directoryUserId når FoxIDs allerede kjenner det

Brukeren identifiseres i FoxIDs med AD objectGUID kodet som base64. Verdien returneres som directoryUserId og er stabil selv om e-post, telefon eller brukernavn endres.

Ved passordautentisering finner komponenten brukerens distinguished name og binder deretter til AD som den brukeren med det innsendte passordet. Dette unngår tvetydige brukeroppslag og støtter alle konfigurerte identifikatortyper.

Ved passordendring validerer AD det nåværende passordet og passordpolicyen.

Hvis FoxIDs passordpolicy er aktivert for Directory Connector, forhåndsvaliderer FoxIDs passordlengde, kompleksitet og passordhistorikk før connectoren kalles. Dette gir brukeren mer presis tilbakemelding for disse kontrollene. AD er fortsatt autoritativt og kan fortsatt avvise passordet etterpå med password_not_accepted, for eksempel på grunn av minimum passordlengde, kompleksitet, passordhistorikk, minimum password age, fine-grained password policy eller et custom password filter.

For set-password må den konfigurerte serviceidentiteten ha delegerte reset-password-rettigheter.

Tilgang for AD-servicekonto

Connectoren bør kjøre med en dedikert AD-serviceidentitet. Ikke gjør identiteten til domeneadministrator. Bruk en vanlig domenebruker eller en egendefinert sikkerhetsgruppe, og deleger bare nødvendige rettigheter på OU-ene connectoren bruker.

For brukeroppslag og autentisering må connector-identiteten ha tillatelse til å søke i hver konfigurerte UserSearchBases OU og lese brukerobjektene og attributtene som brukes av connectoren. En ny dedikert AD-serviceidentitet har ofte allerede denne lesetilgangen som standard, med mindre AD-ACL-ene er strammet inn.

Ved passordautentisering finner connectoren først brukeren med serviceidentiteten og binder deretter til AD som brukeren med det innsendte passordet. Dette krever ikke at serviceidentiteten kjenner eller tilbakestiller brukerens passord.

Ved passordendring, når brukeren oppgir det nåværende passordet, bruker connectoren AD sin password change-adferd, og AD validerer det nåværende passordet og passordpolicyen.

For set-password / password reset skal password reset-rettigheter delegeres på brukerobjektene i hver konfigurerte UserSearchBases OU der connectoren skal støtte password reset. I Active Directory Users and Computers høyreklikker du på user OU-en som connectoren bruker, velger Delegate Control..., velger connector-identiteten og på trinnet Tasks to Delegate velger du Reset user passwords and force password change at next logon.

Deleger Reset user passwords and force password change at next logon-rettigheten til connector-identiteten

Deleger også eventuelle ekstra passordrelaterte rettigheter som domenepolicyen krever, bare hvis miljøet bruker de handlingene. For grupperolle-claims må connector-identiteten ha lesetilgang til de konfigurerte GroupSearchBases. Den må kunne liste group OU-en og lese gruppeattributter som cn, distinguishedName og member.

Konfigurasjon

Konfigurasjon bruker standard .NET-konfigurasjon. Verdier kan settes i appsettings.json, miljøvariabler, IIS-konfigurasjon eller en annen .NET-konfigurasjonsprovider.

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 alltid fra AD objectGUID og returneres base64-kodet. Den er ikke konfigurerbar.

UserIdentifiers styrer hvilke AD-attributter som kan brukes til oppslag via e-post, telefon og brukernavn og returneres som brukeridentifikatorer på toppnivå. Minst én av Email, Phone eller Username må være konfigurert og returnert fra AD for et gyldig connector-svar. Fjern en identifier-mapping hvis feltet ikke skal brukes til oppslag eller returneres på toppnivå. Den samme AD-attributten kan fortsatt konfigureres som et claim i Claims.

Viktige innstillinger:

  • ApiKey: Delt secret som FoxIDs bruker til å autentisere mot connectoren. FoxIDs sender dette som HTTP Basic authentication med API ID directory_connector. Bruk en sterk unik verdi og lagre den som en miljøvariabel eller IIS-innstilling der det er mulig.
  • ActiveDirectory:Domain: AD-domenenavnet, for eksempel example.local.
  • ActiveDirectory:Server: Valgfri domenekontroller eller LDAP-endpoint. Hvis den utelates, brukes Domain.
  • ActiveDirectory:Port: LDAP-port. Bruk 636 for LDAPS.
  • ActiveDirectory:UseSsl: Aktiverer LDAPS. Hold dette aktivert for passordoperasjoner med mindre en annen sikker kanal er garantert.
  • ActiveDirectory:Bind:Mode: Integrated bruker IIS application pool-identiteten eller prosessidentiteten. ConfiguredCredentials bruker konfigurert Username og Password.
  • ActiveDirectory:Bind:Username og ActiveDirectory:Bind:Password: Credentials brukes bare når Mode er ConfiguredCredentials. Foretrekk miljøvariabler eller IIS-konfigurasjon for passordet.
  • ActiveDirectory:UserSearchBases: Ett eller flere distinguished names der brukere søkes, for eksempel OU=Users,DC=example,DC=local.
  • ActiveDirectory:GroupSearchBases: Ett eller flere distinguished names der konfigurerte rollegrupper søkes.
  • ActiveDirectory:UserIdentifiers: Valgfrie AD-felt for oppslag og toppnivå brukeridentifikatorer: Email, Phone og Username. Konfigurer minst ett.
  • ActiveDirectory:Claims: Brukerfelt som returneres som claims, for eksempel name, given_name, family_name eller email.
  • ActiveDirectory:GroupClaims: AD-gruppemedlemskap som returneres som claims, typisk role-claims. Se Gruppeclaims for konfigurasjonsdetaljer.

Gruppeclaims

Gruppeclaims er deaktivert som standard. For å aktivere dem legger du til én eller flere oppføringer i ActiveDirectory:GroupClaims.

Hver GroupClaims oppføring definerer claim-typen som skal returneres og hvilke AD-gruppemedlemskap som skal produsere det claimet. Claim er påkrevd og er typisk role.

Det finnes tre vanlige konfigurasjoner:

"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 verken GroupDistinguishedName eller GroupName er konfigurert, søker connectoren i de konfigurerte GroupSearchBases og returnerer ett claim for hver matchende gruppe som brukeren er medlem av. I denne modusen skal du ikke konfigurere Value; claim-verdien må komme fra ValueAttribute. Med standard ValueAttribute satt til cn returnerer en gruppe med navnet admin_access:

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

Bruk GroupDistinguishedName når du kjenner den eksakte DN-en til AD-gruppen. Dette unngår søk etter navn og er det mest presise alternativet.

Bruk GroupName når connectoren skal finne én enkelt gruppe ut fra cn-verdien i GroupSearchBases. Søket må matche nøyaktig én gruppe. Hvis mer enn én gruppe med samme cn finnes i de konfigurerte GroupSearchBases, feiler forespørselen fordi gruppemappingen er tvetydig.

Bruk Value bare når GroupDistinguishedName eller GroupName er konfigurert og det returnerte claimet skal ha en fast verdi som er uavhengig av AD-gruppens navn. For eksempel kan en gruppe med DN CN=Employees,OU=Groups,DC=example,DC=local returnere role-verdien employees.

Hvis Value ikke er satt, leser connectoren det konfigurerte ValueAttribute fra den matchede AD-gruppen. Standard ValueAttribute er cn, som returnerer AD-gruppens navn som claim-verdi. Konfigurer bare et annet gruppeattributt hvis det attributtet finnes på gruppeobjektet og inneholder verdien som skal sendes til FoxIDs.

IncludeNestedGroups styrer hvordan medlemskap kontrolleres:

  • true bruker AD sin rekursive matchingsregel, slik at claimet returneres hvis brukeren er direkte medlem eller er medlem gjennom nestede grupper.
  • false kontrollerer bare direkte medlemskap i den matchede gruppen.

IIS-installasjon

Komponenten deployes med Xcopy. Den har ingen database og ingen installer. Oppdatering eller rollback utføres ved å erstatte filene i IIS-nettstedets mappe mens den miljøspesifikke konfigurasjonen beholdes.

  1. Installer ASP.NET Core Hosting Bundle for .NET 10 (direkte nedlasting) på Windows-serveren.
  2. Opprett en mappe, for eksempel C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
  3. Pakk ut release-zippen i mappen.
  4. Konfigurer appsettings.json eller miljøvariabler.
  5. Opprett en IIS application pool.
  6. Sett application pool-identiteten til en domeneservicekonto, eller konfigurer bind-credentials i appsettings.json.
  7. Opprett et IIS-site eller en IIS-application som peker til mappen.
  8. Bind nettstedet til HTTPS.
  9. Opprett loggmappen C:\inetpub\logs\LogFiles\foxids-ad, og gi application pool-identiteten skrivetilgang. Hvis IIS-application poolen for eksempel heter FoxIDs.DirectoryConnector.AD, gir du skrivetilgang til IIS AppPool\FoxIDs.DirectoryConnector.AD.
  10. Verifiser GET /health.

For en FoxIDs API URL bruker du connectorens base URL, for eksempel:

https://connector.example.com

FoxIDs legger til authentication, change-password og set-password til den base URL-en.

TLS-sertifikat

FoxIDs kaller connectoren over HTTPS, så IIS-nettstedet bør ha et betrodd TLS-sertifikat. Du kan bruke ditt eget sertifikat eller valgfritt opprette et gratis Let's Encrypt-sertifikat med win-acme.

Med win-acme laster du ned den nyeste releasen win-acme.v2.x.x.x64.pluggable.zip, pakker den ut til en permanent mappe, kjører wacs.exe fra en forhøyet Command Prompt og velger IIS-nettstedet som hoster Directory Connector. Win-acme legger til HTTPS-bindingen og registrerer automatisk sertifikatfornyelse i Windows Task Scheduler.

Se hele win-acme-flyten i FoxIDs Windows / IIS HTTP and HTTPS guide.

FoxIDs-miljøkonfigurasjon

Når connectoren er installert og tilgjengelig over HTTPS, aktiveres den i FoxIDs-miljøet:

  1. Åpne FoxIDs Control Client.
  2. Velg den tenanten og det miljøet som skal bruke connectoren.
  3. Gå til Settings > Environment.
  4. Finn Directory connector settings.
  5. Aktiver directory connector.
  6. Angi connectorens API URL, for eksempel https://connector.example.com.
  7. Angi samme secret som connectorens ApiKey.
  8. Velg om FoxIDs skal lagre en lokal passordkopi og om FoxIDs passordpolicy skal brukes før connector-kallet.

Når FoxIDs passordpolicy er aktivert, validerer FoxIDs passordlengde, kompleksitet og passordhistorikk før connectoren kalles. Dette gir brukerne umiddelbar FoxIDs policy-feedback, men AD er fortsatt autoritativt og kan fortsatt avvise et passord med password_not_accepted på grunn av minimum passordlengde, kompleksitet, passordhistorikk, minimum password age, fine-grained password policy eller et custom password filter.

FoxIDs Directory Connector-innstillinger for Active Directory

API URL-en i FoxIDs må peke på connectorens base URL. FoxIDs legger til endepunktsnavnene når den kaller connectoren.

Som standard er bare innlogging med e-postadresse aktivert i Login authentication method. Hvis brukerne skal kunne logge inn med brukernavn eller telefonnummer, aktiverer du de tilsvarende brukeridentifikatorene i Login authentication method.

Eksemplet nedenfor har både brukernavn og e-post aktivert.

FoxIDs Login authentication method-brukeridentifikatorer for Directory Connector

Patching og oppdateringer

  1. Last ned den nye releasen FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip og les release notes.
  2. Pakk ut zip-filen til en midlertidig mappe og kopier over de nåværende appsettings*.json filene, eller behold secrets i IIS-miljøvariabler.
  3. Stopp IIS-nettstedet eller application poolen.
  4. Gi nytt navn til eller kopier den nåværende mappen til en backupmappe, for eksempel C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
  5. Xcopy de nye filene til C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory og verifiser NTFS-rettigheter for application pool-identiteten.
  6. Start application poolen og verifiser GET /health, og test deretter en Directory Connector-innlogging eller en passordoperasjon.
  7. Hvis rollback er nødvendig, stopper du application poolen, gjenoppretter backupmappen til live-stien og starter application poolen på nytt.

Standard-web.config skriver ASP.NET Core stdout-logger til C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Hold stdout-logging aktivert til connectoren er verifisert, og vurder deretter å deaktivere den eller videresende loggene til miljøets normale loggsystem etter validering i produksjon.

Ditt personvern

Ditt personvern

Vi bruker cookies for å gjøre opplevelsen av nettstedene våre bedre. Klikk på 'Godta alle cookies' for å samtykke til bruk av cookies. For å reservere deg mot ikke-nødvendige cookies, klikk på 'Kun nødvendige cookies'.

Besøk vår personvernerklæring for mer