Active Directory Directory Connector

Active Directory Directory Connector to komponent FoxIDs, który implementuje API Directory Connector dla jednej domeny AD/LDAP.

Zainstaluj komponent w środowisku Windows klienta, gdzie może łączyć się z kontrolerami domeny. FoxIDs wywołuje komponent przez HTTPS, a komponent weryfikuje użytkowników, zmienia hasła, ustawia hasła oraz zwraca właściwości użytkownika i claims z Active Directory.

Connector jest instalowany i konfigurowany na serwerze Windows/IIS blisko Active Directory. W FoxIDs jest następnie włączany w środowisku FoxIDs w Settings > Environment > Directory connector settings, gdzie konfiguruje się API URL i secret connectora.

Komponent jest publikowany jako Windows zip razem z wydaniami FoxIDs:

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

Endpoints

Komponent udostępnia:

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

Endpoint /health nie wymaga uwierzytelnienia i zwraca tylko minimalny status. Sprawdza wymaganą konfigurację, AD bind, dostęp do user search-base oraz opcjonalny dostęp do group search-base. Nie testuje delegowanych uprawnień dla set-password / password reset. Szczegółowe błędy i stack trace są logowane po stronie serwera i nie są zwracane przez endpoint.

Przykładowa odpowiedź:

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

Odpowiedź zawiera tylko status, adBind, userSearch i groupSearch. status ma wartość ok tylko wtedy, gdy wymagana konfiguracja jest poprawna, AD bind kończy się sukcesem, dostęp do user search-base kończy się sukcesem, a dostęp do group search-base nie zakończył się błędem. groupSearch ma wartość not_configured, gdy nie skonfigurowano żadnej group search base. Jeśli sprawdzenie nie może zostać wykonane, ponieważ wcześniejsze sprawdzenie zakończyło się błędem albo brakuje konfiguracji, pole jest zwracane jako unknown.

Wymagania

Windows Server z IIS.
ASP.NET Core Hosting Bundle dla .NET 10.
Dostęp sieciowy z serwera IIS do skonfigurowanego kontrolera domeny.
LDAPS lub inny bezpieczny kanał dla operacji haseł.
Jedna domena AD na deployment connectora.
Konto serwisowe domeny, jeśli używane są skonfigurowane credentials.
Delegowane uprawnienie AD do password reset, jeśli set-password ma być obsługiwane.

Zalecana konfiguracja to serwer IIS dołączony do domeny, którego application pool działa jako konto serwisowe domeny. Skonfigurowane bind-credentials są również obsługiwane przez appsettings.json lub zmienne środowiskowe.

Uwierzytelnianie

Skonfiguruj silny klucz API w appsettings.json. FoxIDs wysyła HTTP Basic authentication z API ID directory_connector i skonfigurowanym secretem.

Używaj nagłówka X-FoxIDs-Api-Key: <api-key> tylko wtedy, gdy reverse proxy przed Directory Connector obsługuje Basic authentication, zanim żądanie dotrze do komponentu, i przepisuje api-key.

Wyszukiwanie i bind w AD

Komponent najpierw wyszukuje w AD przy użyciu skonfigurowanej tożsamości serwisowej. Obsługuje wyszukiwanie po:

e-mailu
telefonie
nazwie użytkownika
directoryUserId, gdy FoxIDs już go zna

Użytkownik jest identyfikowany w FoxIDs przez AD objectGUID zakodowany jako base64. Wartość jest zwracana jako directoryUserId i pozostaje stabilna, nawet jeśli e-mail, telefon lub nazwa użytkownika się zmieni.

Podczas uwierzytelniania hasłem komponent znajduje distinguished name użytkownika, a następnie wykonuje bind do AD jako ten użytkownik z podanym hasłem. Pozwala to uniknąć niejednoznacznego wyszukiwania użytkownika i obsługuje wszystkie skonfigurowane typy identyfikatorów.

Podczas zmiany hasła AD weryfikuje bieżące hasło i politykę haseł.

Jeśli polityka haseł FoxIDs jest włączona dla Directory Connector, FoxIDs wstępnie weryfikuje długość, złożoność i historię hasła przed wywołaniem connectora. Daje to użytkownikowi dokładniejsze informacje zwrotne dla tych kontroli. AD pozostaje źródłem rozstrzygającym i nadal może później odrzucić hasło z password_not_accepted, na przykład z powodu minimalnej długości hasła, złożoności, historii haseł, minimum password age, fine-grained password policy lub custom password filter.

Dla set-password skonfigurowana tożsamość serwisowa musi mieć delegowane uprawnienia reset-password.

Dostęp konta serwisowego AD

Connector powinien działać z dedykowaną tożsamością serwisową AD. Nie nadawaj tej tożsamości roli administratora domeny. Użyj zwykłego użytkownika domenowego lub dedykowanej grupy zabezpieczeń i deleguj tylko wymagane uprawnienia na OU używanych przez connector.

Do wyszukiwania użytkowników i uwierzytelniania tożsamość connectora musi mieć uprawnienie do wyszukiwania w każdej skonfigurowanej OU UserSearchBases oraz odczytu obiektów użytkowników i atrybutów używanych przez connector. Nowa dedykowana tożsamość serwisowa AD często ma już ten dostęp do odczytu domyślnie, o ile listy ACL w AD nie zostały ograniczone.

Podczas uwierzytelniania hasłem connector najpierw znajduje użytkownika za pomocą tożsamości serwisowej, a następnie wykonuje bind do AD jako ten użytkownik z podanym hasłem. Nie wymaga to, aby tożsamość serwisowa znała lub resetowała hasło użytkownika.

Podczas zmiany hasła, gdy użytkownik podaje bieżące hasło, connector używa zachowania AD dla password change, a AD weryfikuje bieżące hasło i politykę haseł.

Dla set-password / password reset deleguj prawa password reset na obiektach użytkowników w każdej skonfigurowanej OU UserSearchBases, w której connector ma obsługiwać password reset. W Active Directory Users and Computers kliknij prawym przyciskiem myszy user OU używaną przez connector, wybierz Delegate Control..., wybierz tożsamość connectora, a w kroku Tasks to Delegate wybierz Reset user passwords and force password change at next logon.

Delegowanie prawa Reset user passwords and force password change at next logon do tożsamości connectora

Deleguj także wszelkie dodatkowe uprawnienia związane z hasłami wymagane przez politykę domeny, tylko wtedy, gdy środowisko korzysta z tych operacji. Dla claims ról grup tożsamość connectora musi mieć dostęp do odczytu skonfigurowanych GroupSearchBases. Musi móc listować OU grup i czytać atrybuty grup, takie jak cn, distinguishedName oraz member.

Konfiguracja

Konfiguracja używa standardowej konfiguracji .NET. Wartości można ustawić w appsettings.json, zmiennych środowiskowych, konfiguracji IIS lub innym providerze konfiguracji .NET.

Przykład:

{
	"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 jest zawsze mapowany z AD objectGUID i zwracany w postaci zakodowanej base64. Nie można go konfigurować.

UserIdentifiers określa, które atrybuty AD mogą być używane do wyszukiwania po e-mailu, telefonie i nazwie użytkownika oraz zwracane jako identyfikatory użytkownika najwyższego poziomu. Co najmniej jeden z Email, Phone lub Username musi być skonfigurowany i zwracany z AD, aby odpowiedź connectora była prawidłowa. Usuń mapowanie identyfikatora, jeśli dane pole nie powinno być używane do wyszukiwania ani zwracane na poziomie najwyższym. Ten sam atrybut AD nadal może być skonfigurowany jako claim w Claims.

Ważne ustawienia:

ApiKey: współdzielony secret używany przez FoxIDs do uwierzytelnienia wobec connectora. FoxIDs wysyła go jako HTTP Basic authentication z API ID directory_connector. Użyj silnej, unikalnej wartości i przechowuj ją jako zmienną środowiskową lub ustawienie IIS tam, gdzie to możliwe.
ActiveDirectory:Domain: nazwa domeny AD, np. example.local.
ActiveDirectory:Server: opcjonalny kontroler domeny lub endpoint LDAP. Jeśli pominięty, używane jest Domain.
ActiveDirectory:Port: port LDAP. Użyj 636 dla LDAPS.
ActiveDirectory:UseSsl: włącza LDAPS. Pozostaw tę opcję włączoną dla operacji haseł, chyba że zagwarantowano inny bezpieczny kanał.
ActiveDirectory:Bind:Mode: Integrated używa tożsamości IIS application pool lub tożsamości procesu. ConfiguredCredentials używa skonfigurowanych Username i Password.
ActiveDirectory:Bind:Username i ActiveDirectory:Bind:Password: credentials są używane tylko wtedy, gdy Mode ma wartość ConfiguredCredentials. Dla hasła preferuj zmienne środowiskowe lub konfigurację IIS.
ActiveDirectory:UserSearchBases: jeden lub więcej distinguished names, w których wyszukiwani są użytkownicy, np. OU=Users,DC=example,DC=local.
ActiveDirectory:GroupSearchBases: jeden lub więcej distinguished names, w których wyszukiwane są skonfigurowane grupy ról.
ActiveDirectory:UserIdentifiers: opcjonalne atrybuty AD do wyszukiwania i identyfikatorów użytkownika najwyższego poziomu: Email, Phone i Username. Skonfiguruj co najmniej jeden.
ActiveDirectory:Claims: atrybuty użytkownika zwracane jako claims, na przykład name, given_name, family_name lub email.
ActiveDirectory:GroupClaims: członkostwa w grupach AD zwracane jako claims, zwykle claims role. Zobacz Claims grup, aby uzyskać szczegóły konfiguracji.

Claims grup

Claims grup są domyślnie wyłączone. Aby je włączyć, dodaj jeden lub więcej wpisów do ActiveDirectory:GroupClaims.

Każdy wpis GroupClaims definiuje typ claim, który ma zostać zwrócony, oraz to, które członkostwa w grupach AD mają wygenerować ten claim. Claim jest wymagany i zwykle ma wartość role.

Istnieją trzy typowe konfiguracje:

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

Jeśli ani GroupDistinguishedName, ani GroupName nie jest skonfigurowane, connector przeszukuje skonfigurowane GroupSearchBases i zwraca jeden claim dla każdej pasującej grupy, której członkiem jest użytkownik. W tym trybie nie konfiguruj Value; wartość claim musi pochodzić z ValueAttribute. Przy domyślnym ValueAttribute równym cn grupa o nazwie admin_access zwraca:

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

Użyj GroupDistinguishedName, gdy znasz dokładny DN grupy AD. Pozwala to uniknąć wyszukiwania po nazwie i jest najbardziej precyzyjną opcją.

Użyj GroupName, gdy connector ma znaleźć pojedynczą grupę na podstawie jej wartości cn w GroupSearchBases. Wyszukiwanie musi dopasować dokładnie jedną grupę. Jeśli w skonfigurowanych GroupSearchBases istnieje więcej niż jedna grupa z tym samym cn, żądanie kończy się niepowodzeniem, ponieważ mapowanie grupy jest niejednoznaczne.

Używaj Value tylko wtedy, gdy skonfigurowano GroupDistinguishedName lub GroupName, a zwracany claim ma mieć stałą wartość niezależną od nazwy grupy AD. Na przykład grupa o DN CN=Employees,OU=Groups,DC=example,DC=local może zwrócić wartość role employees.

Jeśli Value nie jest ustawione, connector odczytuje skonfigurowane ValueAttribute z dopasowanej grupy AD. Domyślne ValueAttribute to cn, co zwraca nazwę grupy AD jako wartość claim. Skonfiguruj inny atrybut grupy tylko wtedy, gdy istnieje on na obiekcie grupy i zawiera wartość, która ma zostać wysłana do FoxIDs.

IncludeNestedGroups określa, jak sprawdzane jest członkostwo:

true używa reguły rekursywnego dopasowania AD, więc claim jest zwracany, jeśli użytkownik jest członkiem bezpośrednim albo przez zagnieżdżone grupy.
false sprawdza tylko bezpośrednie członkostwo w dopasowanej grupie.

Instalacja IIS

Komponent jest wdrażany przez Xcopy. Nie ma bazy danych ani instalatora. Aktualizacja lub rollback polega na zastąpieniu plików w folderze witryny IIS z zachowaniem konfiguracji specyficznej dla środowiska.

Zainstaluj ASP.NET Core Hosting Bundle dla .NET 10 (bezpośrednie pobranie) na serwerze Windows.
Utwórz folder, np. C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
Rozpakuj zip release do folderu.
Skonfiguruj appsettings.json lub zmienne środowiskowe.
Utwórz IIS application pool.
Ustaw tożsamość application pool jako konto serwisowe domeny albo skonfiguruj bind-credentials w appsettings.json.
Utwórz IIS site albo IIS application wskazującą na folder.
Powiąż site z HTTPS.
Utwórz folder logów C:\inetpub\logs\LogFiles\foxids-ad i nadaj tożsamości puli aplikacji dostęp do zapisu. Na przykład jeśli pula aplikacji IIS nazywa się FoxIDs.DirectoryConnector.AD, nadaj dostęp do zapisu dla IIS AppPool\FoxIDs.DirectoryConnector.AD.
Zweryfikuj GET /health.

Dla FoxIDs API URL użyj base URL connectora, na przykład:

https://connector.example.com

FoxIDs dodaje do tej base URL nazwy authentication, change-password i set-password.

Certyfikat TLS

FoxIDs wywołuje connector przez HTTPS, więc IIS site powinien mieć zaufany certyfikat TLS. Możesz użyć własnego certyfikatu albo opcjonalnie utworzyć bezpłatny certyfikat Let's Encrypt przy użyciu win-acme.

Z win-acme pobierz najnowszy release win-acme.v2.x.x.x64.pluggable.zip, rozpakuj go do stałego folderu, uruchom wacs.exe z podwyższonego Command Prompt i wybierz IIS site hostujący Directory Connector. Win-acme dodaje powiązanie HTTPS i rejestruje automatyczne odnawianie certyfikatu w Windows Task Scheduler.

Pełny proces znajduje się w FoxIDs Windows / IIS HTTP and HTTPS guide.

Konfiguracja środowiska FoxIDs

Po zainstalowaniu connectora i udostępnieniu go przez HTTPS włącz go w środowisku FoxIDs:

Otwórz FoxIDs Control Client.
Wybierz tenant i środowisko, które ma używać connectora.
Przejdź do Settings > Environment.
Znajdź Directory connector settings.
Włącz directory connector.
Wprowadź API URL connectora, na przykład https://connector.example.com.
Wprowadź ten sam secret co ApiKey connectora.
Wybierz, czy FoxIDs ma zapisywać lokalną kopię hasła i czy polityka haseł FoxIDs ma być stosowana przed wywołaniem connectora.

Gdy polityka haseł FoxIDs jest włączona, FoxIDs weryfikuje długość, złożoność i historię hasła przed wywołaniem connectora. Daje to użytkownikom natychmiastową informację zwrotną z polityki FoxIDs, ale AD pozostaje źródłem rozstrzygającym i nadal może odrzucić hasło z password_not_accepted z powodu minimalnej długości hasła, złożoności, historii haseł, minimum password age, fine-grained password policy lub custom password filter.

Ustawienia FoxIDs Directory Connector dla Active Directory

API URL w FoxIDs musi wskazywać base URL connectora. FoxIDs dodaje nazwy endpointów, gdy wywołuje connector.

Domyślnie w Login authentication method włączone jest tylko logowanie adresem e-mail. Jeśli użytkownicy mają móc logować się nazwą użytkownika lub numerem telefonu, włącz odpowiednie identyfikatory użytkownika w Login authentication method.

Poniższy przykład ma włączoną zarówno nazwę użytkownika, jak i e-mail.

Identyfikatory użytkownika FoxIDs Login authentication method dla Directory Connector

Patching i aktualizacje

Pobierz nowy release FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip i przeczytaj release notes.
Rozpakuj plik zip do tymczasowego folderu i skopiuj do niego bieżące pliki appsettings*.json albo pozostaw secrets w zmiennych środowiskowych IIS.
Zatrzymaj site IIS albo application pool.
Zmień nazwę bieżącego folderu lub skopiuj go do folderu kopii zapasowej, np. C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
Skopiuj nowe pliki przy użyciu Xcopy do C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory i zweryfikuj uprawnienia NTFS dla tożsamości application pool.
Uruchom application pool i zweryfikuj GET /health, a następnie przetestuj logowanie przez Directory Connector lub operację na haśle.
Jeśli potrzebny jest rollback, zatrzymaj application pool, przywróć folder kopii zapasowej do ścieżki produkcyjnej i uruchom application pool ponownie.

Domyślny web.config zapisuje logi ASP.NET Core stdout do C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Pozostaw stdout logging włączony do momentu zweryfikowania connectora, a następnie rozważ jego wyłączenie lub przekazywanie logów do standardowego systemu logowania środowiska po walidacji produkcyjnej.