Active Directory Directory Connector

Active Directory Directory Connector är en FoxIDs-komponent som implementerar Directory Connector-API:t för en AD/LDAP-domän.

Installera komponenten i kundens Windows-miljö där den kan nå domänkontrollanterna. FoxIDs anropar komponenten över HTTPS, och komponenten validerar användare, ändrar lösenord, sätter lösenord och returnerar användaregenskaper och claims från Active Directory.

Connectorn installeras och konfigureras på Windows/IIS-servern nära Active Directory. I FoxIDs aktiveras den sedan på FoxIDs-miljön under Settings > Environment > Directory connector settings, där connectorns API URL och secret konfigureras.

Komponenten publiceras som en Windows-zip tillsammans med FoxIDs-versioner:

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

Endpoints

Komponenten exponerar:

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

/health endpointet är inte autentiserat och returnerar endast minimal status. Det kontrollerar nödvändig konfiguration, AD-bind, åtkomst till user search-base och valfri åtkomst till group search-base. Det testar inte delegerade rättigheter för set-password / password reset. Detaljerade fel och stack traces loggas på servern och returneras inte av endpointet.

Exempelsvar:

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

Svaret innehåller endast status, adBind, userSearch och groupSearch. status är ok endast när nödvändig konfiguration är giltig, AD-bind lyckas, åtkomst till user search-base lyckas och group search-base åtkomst inte har misslyckats. groupSearch är not_configured när ingen group search base är konfigurerad. Om en kontroll inte kan utföras eftersom en tidigare kontroll har misslyckats eller konfiguration saknas returneras fältet som unknown.

Krav

  • Windows Server med IIS.
  • ASP.NET Core Hosting Bundle för .NET 10.
  • Nätverksåtkomst från IIS-servern till den konfigurerade domänkontrollanten.
  • LDAPS eller en annan säker kanal för lösenordsoperationer.
  • En AD-domän per connector-deployment.
  • Ett domänservicekonto om konfigurerade credentials används.
  • Delegerad AD-rättighet för password reset om set-password ska stödjas.

En domänansluten IIS-server där application pool körs som ett domänservicekonto är den rekommenderade konfigurationen. Konfigurerade bind-credentials stöds också via appsettings.json eller miljövariabler.

Autentisering

Konfigurera en stark API-nyckel i appsettings.json. FoxIDs skickar HTTP Basic authentication med API ID directory_connector och den konfigurerade secreten.

Använd endast headern X-FoxIDs-Api-Key: <api-key> om en reverse proxy framför Directory Connector hanterar Basic authentication innan begäran når komponenten och skriver om api-key.

AD-uppslag och bindning

Komponenten söker först i AD med den konfigurerade serviceidentiteten. Den stöder uppslag via:

  • e-post
  • telefon
  • användarnamn
  • directoryUserId när FoxIDs redan känner till det

Användaren identifieras i FoxIDs med AD objectGUID kodat som base64. Värdet returneras som directoryUserId och är stabilt även om e-post, telefon eller användarnamn ändras.

Vid lösenordsautentisering hittar komponenten användarens distinguished name och binder sedan till AD som den användaren med det inskickade lösenordet. Det undviker tvetydiga användaruppslag och stöder alla konfigurerade identifikatortyper.

Vid lösenordsbyte validerar AD det aktuella lösenordet och lösenordspolicyn.

Om FoxIDs lösenordspolicy är aktiverad för Directory Connector förvaliderar FoxIDs lösenordslängd, komplexitet och lösenordshistorik innan connectorn anropas. Det ger användaren mer precis feedback för dessa kontroller. AD är fortfarande auktoritativt och kan fortfarande avvisa lösenordet efteråt med password_not_accepted, till exempel på grund av minsta lösenordslängd, komplexitet, lösenordshistorik, minimum password age, fine-grained password policy eller ett custom password filter.

För set-password måste den konfigurerade serviceidentiteten ha delegerade reset-password-rättigheter.

Åtkomst för AD-servicekonto

Connectorn bör köras med en dedikerad AD-serviceidentitet. Gör inte identiteten till domänadministratör. Använd en vanlig domänanvändare eller en anpassad säkerhetsgrupp, och delegera endast nödvändiga rättigheter på de OU:er connectorn använder.

För användaruppslag och autentisering måste connector-identiteten ha behörighet att söka i varje konfigurerad UserSearchBases OU och läsa användarobjekten och attributen som används av connectorn. En ny dedikerad AD-serviceidentitet har ofta redan denna läsåtkomst som standard, om AD-ACL:erna inte har begränsats.

Vid lösenordsautentisering hittar connectorn först användaren med serviceidentiteten och binder sedan till AD som användaren med det inskickade lösenordet. Det kräver inte att serviceidentiteten känner till eller återställer användarens lösenord.

Vid lösenordsbyte, när användaren anger det aktuella lösenordet, använder connectorn AD:s password change-beteende och AD validerar det aktuella lösenordet och lösenordspolicyn.

För set-password / password reset ska password reset-rättigheter delegeras på användarobjekten i varje konfigurerad UserSearchBases OU där connectorn ska stödja password reset. I Active Directory Users and Computers högerklickar du på den user OU som connectorn använder, väljer Delegate Control..., väljer connector-identiteten och i steget Tasks to Delegate väljer du Reset user passwords and force password change at next logon.

Delegera Reset user passwords and force password change at next logon-rättigheten till connector-identiteten

Delegera också eventuella ytterligare lösenordsrelaterade rättigheter som domänpolicyn kräver, endast om miljön använder de åtgärderna. För grupproll-claims måste connector-identiteten ha läsåtkomst till de konfigurerade GroupSearchBases. Den måste kunna lista group OU:n och läsa gruppattribut som cn, distinguishedName och member.

Konfiguration

Konfigurationen använder standard .NET-konfiguration. Värden kan anges i appsettings.json, miljövariabler, IIS-konfiguration eller en annan .NET-konfigurationsprovider.

Exempel:

{
	"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 mappas alltid från AD objectGUID och returneras base64-kodad. Den är inte konfigurerbar.

UserIdentifiers styr vilka AD-attribut som kan användas för uppslag via e-post, telefon och användarnamn och returneras som användaridentifikatorer på toppnivå. Minst en av Email, Phone eller Username måste vara konfigurerad och returneras från AD för ett giltigt connector-svar. Ta bort en identifier-mappning om fältet inte ska användas för uppslag eller returneras på toppnivå. Samma AD-attribut kan fortfarande konfigureras som ett claim i Claims.

Viktiga inställningar:

  • ApiKey: Delad secret som FoxIDs använder för att autentisera mot connectorn. FoxIDs skickar detta som HTTP Basic authentication med API ID directory_connector. Använd ett starkt unikt värde och lagra det som en miljövariabel eller IIS-inställning där det är möjligt.
  • ActiveDirectory:Domain: AD-domännamnet, till exempel example.local.
  • ActiveDirectory:Server: Valfri domänkontrollant eller LDAP-endpoint. Om den utelämnas används Domain.
  • ActiveDirectory:Port: LDAP-port. Använd 636 för LDAPS.
  • ActiveDirectory:UseSsl: Aktiverar LDAPS. Behåll detta aktiverat för lösenordsoperationer om inte en annan säker kanal garanteras.
  • ActiveDirectory:Bind:Mode: Integrated använder IIS application pool-identiteten eller processidentiteten. ConfiguredCredentials använder det konfigurerade Username och Password.
  • ActiveDirectory:Bind:Username och ActiveDirectory:Bind:Password: Credentials används endast när Mode är ConfiguredCredentials. Föredra miljövariabler eller IIS-konfiguration för lösenordet.
  • ActiveDirectory:UserSearchBases: Ett eller flera distinguished names där användare söks, till exempel OU=Users,DC=example,DC=local.
  • ActiveDirectory:GroupSearchBases: Ett eller flera distinguished names där konfigurerade rollgrupper söks.
  • ActiveDirectory:UserIdentifiers: Valfria AD-fält för uppslag och användaridentifierare på toppnivå: Email, Phone och Username. Konfigurera minst ett.
  • ActiveDirectory:Claims: Användarfält som returneras som claims, till exempel name, given_name, family_name eller email.
  • ActiveDirectory:GroupClaims: AD-gruppmedlemskap som returneras som claims, vanligtvis role-claims. Se Gruppclaims för konfigurationsdetaljer.

Gruppclaims

Gruppclaims är inaktiverade som standard. För att aktivera dem lägger du till en eller flera poster i ActiveDirectory:GroupClaims.

Varje GroupClaims post definierar claim-typen som ska returneras och vilka AD-gruppmedlemskap som ska producera det claimet. Claim är obligatoriskt och är vanligtvis role.

Det finns tre vanliga 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"
	}
]

Om varken GroupDistinguishedName eller GroupName är konfigurerat söker connectorn i de konfigurerade GroupSearchBases och returnerar ett claim för varje matchande grupp som användaren är medlem i. I detta läge ska du inte konfigurera Value; claim-värdet måste komma från ValueAttribute. Med standard ValueAttribute satt till cn returnerar en grupp med namnet admin_access:

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

Använd GroupDistinguishedName när du känner till den exakta DN:n för AD-gruppen. Det undviker sökning efter namn och är det mest precisa alternativet.

Använd GroupName när connectorn ska hitta en enskild grupp utifrån dess cn-värde i GroupSearchBases. Sökningen måste matcha exakt en grupp. Om mer än en grupp med samma cn finns i de konfigurerade GroupSearchBases misslyckas begäran eftersom gruppmappningen är tvetydig.

Använd endast Value när GroupDistinguishedName eller GroupName är konfigurerat och det returnerade claimet ska ha ett fast värde som är oberoende av AD-gruppens namn. Till exempel kan en grupp med DN CN=Employees,OU=Groups,DC=example,DC=local returnera role-värdet employees.

Om Value inte är satt läser connectorn det konfigurerade ValueAttribute från den matchade AD-gruppen. Standard ValueAttribute är cn, vilket returnerar AD-gruppens namn som claim-värde. Konfigurera ett annat gruppattribut endast om det attributet finns på gruppobjektet och innehåller det värde som ska skickas till FoxIDs.

IncludeNestedGroups styr hur medlemskap kontrolleras:

  • true använder AD:s rekursiva matchningsregel, så claimet returneras om användaren är direkt medlem eller är medlem via nästlade grupper.
  • false kontrollerar endast direkt medlemskap i den matchade gruppen.

IIS-installation

Komponenten distribueras med Xcopy. Den har ingen databas och ingen installer. Uppdatering eller återställning görs genom att ersätta filerna i IIS-webbplatsens mapp samtidigt som den miljöspecifika konfigurationen behålls.

  1. Installera ASP.NET Core Hosting Bundle för .NET 10 (direkt nedladdning) på Windows-servern.
  2. Skapa en mapp, till exempel C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
  3. Packa upp release-zippen i mappen.
  4. Konfigurera appsettings.json eller miljövariabler.
  5. Skapa en IIS application pool.
  6. Sätt application pool-identiteten till ett domänservicekonto eller konfigurera bind-credentials i appsettings.json.
  7. Skapa ett IIS-site eller en IIS-application som pekar på mappen.
  8. Bind siten till HTTPS.
  9. Skapa loggmappen C:\inetpub\logs\LogFiles\foxids-ad och ge application pool-identiteten skrivåtkomst. Om IIS-application poolen till exempel heter FoxIDs.DirectoryConnector.AD, ge skrivåtkomst till IIS AppPool\FoxIDs.DirectoryConnector.AD.
  10. Verifiera GET /health.

För en FoxIDs API URL använder du connectorns base URL, till exempel:

https://connector.example.com

FoxIDs lägger till authentication, change-password och set-password till den base URL:en.

TLS-certifikat

FoxIDs anropar connectorn över HTTPS, så IIS-siten bör ha ett betrott TLS-certifikat. Du kan använda ditt eget certifikat eller valfritt skapa ett kostnadsfritt Let's Encrypt-certifikat med win-acme.

Med win-acme laddar du ned den senaste releasen win-acme.v2.x.x.x64.pluggable.zip, packar upp den till en permanent mapp, kör wacs.exe från en upphöjd Command Prompt och väljer IIS-siten som hostar Directory Connector. Win-acme lägger till HTTPS-bindningen och registrerar automatisk certifikatförnyelse i Windows Task Scheduler.

Se hela win-acme-flödet i FoxIDs Windows / IIS HTTP and HTTPS guide.

FoxIDs-miljökonfiguration

När connectorn är installerad och nåbar över HTTPS aktiveras den i FoxIDs-miljön:

  1. Öppna FoxIDs Control Client.
  2. Välj den tenant och miljö som ska använda connectorn.
  3. Gå till Settings > Environment.
  4. Hitta Directory connector settings.
  5. Aktivera directory connector.
  6. Ange connectorns API URL, till exempel https://connector.example.com.
  7. Ange samma secret som connectorns ApiKey.
  8. Välj om FoxIDs ska spara en lokal lösenordskopia och om FoxIDs lösenordspolicy ska användas före connector-anropet.

När FoxIDs lösenordspolicy är aktiverad validerar FoxIDs lösenordslängd, komplexitet och lösenordshistorik innan connectorn anropas. Det ger användarna omedelbar FoxIDs policy-feedback, men AD är fortfarande auktoritativt och kan fortfarande avvisa ett lösenord med password_not_accepted på grund av minsta lösenordslängd, komplexitet, lösenordshistorik, minimum password age, fine-grained password policy eller ett custom password filter.

FoxIDs Directory Connector-inställningar för Active Directory

API URL:en i FoxIDs måste peka på connectorns base URL. FoxIDs lägger till endpointnamnen när den anropar connectorn.

Som standard är endast inloggning med e-postadress aktiverad i Login authentication method. Om användare ska kunna logga in med användarnamn eller telefonnummer aktiverar du motsvarande användaridentifierare i Login authentication method.

Exemplet nedan har både användarnamn och e-post aktiverade.

FoxIDs Login authentication method-användaridentifierare för Directory Connector

Patchning och uppdateringar

  1. Ladda ned den nya releasen FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip och läs release notes.
  2. Packa upp zip-filen till en temporär mapp och kopiera över de aktuella appsettings*.json filerna eller behåll secrets i IIS-miljövariabler.
  3. Stoppa IIS-siten eller application poolen.
  4. Byt namn på eller kopiera den aktuella mappen till en backupmapp, till exempel C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
  5. Xcopy de nya filerna till C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory och verifiera NTFS-behörigheter för application pool-identiteten.
  6. Starta application poolen och verifiera GET /health, och testa därefter en Directory Connector-inloggning eller en lösenordsoperation.
  7. Om återställning behövs stoppar du application poolen, återställer backupmappen till live-sökvägen och startar application poolen igen.

Standard-web.config skriver ASP.NET Core stdout-loggar till C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Behåll stdout-loggning aktiverad tills connectorn är verifierad och överväg därefter att inaktivera den eller vidarebefordra loggarna till miljöns vanliga loggsystem efter produktionsvalidering.

Din integritet

Din integritet

Vi använder cookies för att göra din upplevelse av våra webbplatser bättre. Klicka på 'Acceptera alla cookies' för att godkänna användningen av cookies. För att avstå från icke-nödvändiga cookies, klicka på 'Endast nödvändiga cookies'.

Besök vår integritetspolicy för mer