Active Directory Directory Connector

Active Directory Directory Connector est un composant FoxIDs qui implémente l'API Directory Connector pour un domaine AD/LDAP.

Installez le composant dans l'environnement Windows du client, où il peut joindre les contrôleurs de domaine. FoxIDs appelle le composant en HTTPS, et le composant valide les utilisateurs, change les mots de passe, définit les mots de passe et retourne les propriétés utilisateur et les claims depuis Active Directory.

Le connector est installé et configuré sur le serveur Windows/IIS proche d'Active Directory. Dans FoxIDs, il est ensuite activé dans l'environnement FoxIDs sous Settings > Environment > Directory connector settings, où vous configurez l'API URL et le secret du connector.

Le composant est publié sous forme de zip Windows avec les versions FoxIDs :

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

Endpoints

Le composant expose :

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

L'endpoint /health n'est pas authentifié et retourne uniquement un statut minimal. Il vérifie la configuration requise, le bind AD, l'accès à la user search-base et l'accès optionnel à la group search-base. Il ne teste pas les droits délégués pour set-password / password reset. Les erreurs détaillées et les stack traces sont journalisées sur le serveur et ne sont pas retournées par l'endpoint.

Exemple de réponse :

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

La réponse contient uniquement status, adBind, userSearch et groupSearch. status vaut ok uniquement lorsque la configuration requise est valide, que le bind AD réussit, que l'accès à la user search-base réussit et que l'accès à la group search-base n'a pas échoué. groupSearch vaut not_configured lorsqu'aucune group search base n'est configurée. Si une vérification ne peut pas être exécutée parce qu'une vérification précédente a échoué ou que la configuration manque, le champ est retourné comme unknown.

Prérequis

Windows Server avec IIS.
ASP.NET Core Hosting Bundle pour .NET 10.
Accès réseau du serveur IIS au contrôleur de domaine configuré.
LDAPS ou un autre canal sécurisé pour les opérations de mot de passe.
Un domaine AD par déploiement du connector.
Un compte de service de domaine si des credentials configurés sont utilisés.
Droit AD délégué de password reset si set-password doit être pris en charge.

Un serveur IIS joint au domaine, dont l'application pool s'exécute avec un compte de service de domaine, est la configuration recommandée. Les bind-credentials configurés sont également pris en charge via appsettings.json ou des variables d'environnement.

Authentification

Configurez une clé API forte dans appsettings.json. FoxIDs envoie HTTP Basic authentication avec l'API ID directory_connector et le secret configuré.

Utilisez l'en-tête X-FoxIDs-Api-Key: <api-key> uniquement si un reverse proxy devant Directory Connector gère Basic authentication avant que la requête n'atteigne le composant et réécrit api-key.

Recherche AD et bind

Le composant recherche d'abord dans AD avec l'identité de service configurée. Il prend en charge la recherche par :

e-mail
téléphone
nom d'utilisateur
directoryUserId lorsque FoxIDs le connaît déjà

L'utilisateur est identifié dans FoxIDs avec l'AD objectGUID encodé en base64. Cette valeur est retournée comme directoryUserId et reste stable même si l'e-mail, le téléphone ou le nom d'utilisateur change.

Pour l'authentification par mot de passe, le composant trouve le distinguished name de l'utilisateur puis se lie à AD comme cet utilisateur avec le mot de passe soumis. Cela évite les recherches d'utilisateur ambiguës et prend en charge tous les types d'identifiants configurés.

Pour le changement de mot de passe, AD valide le mot de passe actuel et la politique de mot de passe.

Si la politique de mot de passe FoxIDs est activée pour Directory Connector, FoxIDs pré-valide la longueur, la complexité et l'historique du mot de passe avant d'appeler le connector. Cela donne à l'utilisateur un retour plus précis pour ces contrôles. AD reste l'autorité et peut encore rejeter le mot de passe ensuite avec password_not_accepted, par exemple à cause d'une longueur minimale, de la complexité, de l'historique des mots de passe, d'un minimum password age, d'une fine-grained password policy ou d'un custom password filter.

Pour set-password, l'identité de service configurée doit disposer de droits délégués de reset-password.

Accès du compte de service AD

Le connector doit s'exécuter avec une identité de service AD dédiée. Ne faites pas de cette identité un administrateur de domaine. Utilisez un utilisateur de domaine standard ou un groupe de sécurité dédié, et déléguez uniquement les droits nécessaires sur les OU utilisées par le connector.

Pour la recherche utilisateur et l'authentification, l'identité du connector doit être autorisée à rechercher dans chaque OU configurée dans UserSearchBases et à lire les objets utilisateur et les attributs utilisés par le connector. Une nouvelle identité de service AD dédiée dispose souvent déjà de cet accès en lecture par défaut, sauf si les ACL AD ont été restreintes.

Pour l'authentification par mot de passe, le connector trouve d'abord l'utilisateur avec l'identité de service puis se lie à AD comme cet utilisateur avec le mot de passe soumis. Cela ne nécessite pas que l'identité de service connaisse ou réinitialise le mot de passe de l'utilisateur.

Pour le changement de mot de passe, lorsque l'utilisateur fournit le mot de passe actuel, le connector utilise le comportement AD de password change, et AD valide le mot de passe actuel ainsi que la politique de mot de passe.

Pour set-password / password reset, déléguez les droits de password reset sur les objets utilisateur dans chaque OU configurée dans UserSearchBases où le connector doit prendre en charge password reset. Dans Active Directory Users and Computers, cliquez avec le bouton droit sur l'user OU utilisée par le connector, sélectionnez Delegate Control..., sélectionnez l'identité du connector puis, à l'étape Tasks to Delegate, sélectionnez Reset user passwords and force password change at next logon.

Déléguer le droit Reset user passwords and force password change at next logon à l'identité du connector

Déléguez également les autorisations supplémentaires liées aux mots de passe requises par la politique de domaine, uniquement si l'environnement utilise ces opérations. Pour les claims de rôle de groupe, l'identité du connector doit avoir un accès en lecture aux GroupSearchBases configurés. Elle doit pouvoir lister l'OU de groupe et lire des attributs de groupe tels que cn, distinguishedName et member.

Configuration

La configuration utilise la configuration .NET standard. Les valeurs peuvent être définies dans appsettings.json, des variables d'environnement, la configuration IIS ou un autre provider de configuration .NET.

Exemple :

{
	"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 est toujours mappé depuis l'AD objectGUID et retourné encodé en base64. Il n'est pas configurable.

UserIdentifiers contrôle quels attributs AD peuvent être utilisés pour la recherche par e-mail, téléphone et nom d'utilisateur et retournés comme identifiants utilisateur de premier niveau. Au moins l'un de Email, Phone ou Username doit être configuré et retourné par AD pour obtenir une réponse connector valide. Supprimez un mapping d'identifiant si ce champ ne doit pas être utilisé pour la recherche ou retourné au niveau supérieur. Le même attribut AD peut toujours être configuré comme claim dans Claims.

Paramètres importants :

ApiKey : secret partagé utilisé par FoxIDs pour s'authentifier auprès du connector. FoxIDs l'envoie en HTTP Basic authentication avec l'API ID directory_connector. Utilisez une valeur forte et unique et stockez-la comme variable d'environnement ou paramètre IIS lorsque c'est possible.
ActiveDirectory:Domain : nom du domaine AD, par exemple example.local.
ActiveDirectory:Server : contrôleur de domaine ou endpoint LDAP optionnel. Si absent, Domain est utilisé.
ActiveDirectory:Port : port LDAP. Utilisez 636 pour LDAPS.
ActiveDirectory:UseSsl : active LDAPS. Gardez-le activé pour les opérations de mot de passe, sauf si un autre canal sécurisé est garanti.
ActiveDirectory:Bind:Mode : Integrated utilise l'identité de l'application pool IIS ou l'identité du processus. ConfiguredCredentials utilise les Username et Password configurés.
ActiveDirectory:Bind:Username et ActiveDirectory:Bind:Password : les credentials sont utilisés uniquement lorsque Mode est ConfiguredCredentials. Préférez les variables d'environnement ou la configuration IIS pour le mot de passe.
ActiveDirectory:UserSearchBases : un ou plusieurs distinguished names où les utilisateurs sont recherchés, par exemple OU=Users,DC=example,DC=local.
ActiveDirectory:GroupSearchBases : un ou plusieurs distinguished names où les groupes de rôles configurés sont recherchés.
ActiveDirectory:UserIdentifiers : attributs AD optionnels pour la recherche et les identifiants utilisateur de premier niveau : Email, Phone et Username. Configurez-en au moins un.
ActiveDirectory:Claims : attributs utilisateur retournés comme claims, par exemple name, given_name, family_name ou email.
ActiveDirectory:GroupClaims : appartenances aux groupes AD retournées comme claims, généralement des claims role. Voir Claims de groupe pour les détails de configuration.

Claims de groupe

Les claims de groupe sont désactivés par défaut. Pour les activer, ajoutez une ou plusieurs entrées à ActiveDirectory:GroupClaims.

Chaque entrée GroupClaims définit le type de claim à retourner et les appartenances aux groupes AD qui doivent produire ce claim. Claim est obligatoire et vaut généralement role.

Il existe trois configurations courantes :

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

Si ni GroupDistinguishedName ni GroupName n'est configuré, le connector recherche dans les GroupSearchBases configurés et retourne un claim pour chaque groupe correspondant dont l'utilisateur est membre. Dans ce mode, ne configurez pas Value ; la valeur du claim doit provenir de ValueAttribute. Avec ValueAttribute défini par défaut sur cn, un groupe nommé admin_access retourne :

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

Utilisez GroupDistinguishedName lorsque vous connaissez le DN exact du groupe AD. Cela évite une recherche par nom et constitue l'option la plus précise.

Utilisez GroupName lorsque le connector doit trouver un groupe unique à partir de sa valeur cn dans GroupSearchBases. La recherche doit correspondre à exactement un groupe. S'il existe plus d'un groupe avec le même cn dans les GroupSearchBases configurés, la requête échoue parce que le mapping de groupe est ambigu.

Utilisez Value uniquement lorsque GroupDistinguishedName ou GroupName est configuré et que le claim retourné doit avoir une valeur fixe, indépendante du nom du groupe AD. Par exemple, un groupe avec le DN CN=Employees,OU=Groups,DC=example,DC=local peut retourner la valeur role employees.

Si Value n'est pas défini, le connector lit le ValueAttribute configuré depuis le groupe AD correspondant. Le ValueAttribute par défaut est cn, ce qui retourne le nom du groupe AD comme valeur de claim. Configurez un autre attribut de groupe uniquement si cet attribut existe sur l'objet groupe et contient la valeur à envoyer à FoxIDs.

IncludeNestedGroups contrôle la manière dont l'appartenance est vérifiée :

true utilise la règle de correspondance récursive d'AD, de sorte que le claim est retourné si l'utilisateur est membre direct ou membre via des groupes imbriqués.
false vérifie uniquement l'appartenance directe au groupe correspondant.

Installation IIS

Le composant est déployé par Xcopy. Il n'a pas de base de données ni d'installateur. La mise à jour ou le rollback se fait en remplaçant les fichiers dans le dossier du site IIS tout en conservant la configuration spécifique à l'environnement.

Installez ASP.NET Core Hosting Bundle pour .NET 10 (téléchargement direct) sur le serveur Windows.
Créez un dossier, par exemple C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
Décompressez le zip de release dans ce dossier.
Configurez appsettings.json ou les variables d'environnement.
Créez un application pool IIS.
Configurez l'identité de l'application pool comme compte de service de domaine, ou configurez les bind-credentials dans appsettings.json.
Créez un site IIS ou une application IIS pointant vers le dossier.
Liez le site en HTTPS.
Créez le dossier de logs C:\inetpub\logs\LogFiles\foxids-ad et accordez l'accès en écriture à l'identité du pool d'applications. Par exemple, si le pool d'applications IIS s'appelle FoxIDs.DirectoryConnector.AD, accordez l'accès en écriture à IIS AppPool\FoxIDs.DirectoryConnector.AD.
Vérifiez GET /health.

Pour l'API URL FoxIDs, utilisez le base URL du connector, par exemple :

https://connector.example.com

FoxIDs ajoute authentication, change-password et set-password à ce base URL.

Certificat TLS

FoxIDs appelle le connector en HTTPS, le site IIS doit donc disposer d'un certificat TLS approuvé. Vous pouvez utiliser votre propre certificat ou créer gratuitement un certificat Let's Encrypt avec win-acme.

Avec win-acme, téléchargez la dernière release win-acme.v2.x.x.x64.pluggable.zip, décompressez-la dans un dossier permanent, exécutez wacs.exe depuis une Command Prompt élevée et sélectionnez le site IIS qui héberge Directory Connector. Win-acme ajoute la liaison HTTPS et enregistre le renouvellement automatique du certificat dans Windows Task Scheduler.

Voir le flux complet dans le FoxIDs Windows / IIS HTTP and HTTPS guide.

Configuration de l'environnement FoxIDs

Une fois le connector installé et joignable en HTTPS, activez-le dans l'environnement FoxIDs :

Ouvrez FoxIDs Control Client.
Sélectionnez le tenant et l'environnement qui doivent utiliser le connector.
Allez dans Settings > Environment.
Trouvez Directory connector settings.
Activez directory connector.
Saisissez l'API URL du connector, par exemple https://connector.example.com.
Saisissez le même secret que l'ApiKey du connector.
Choisissez si FoxIDs doit enregistrer une copie locale du mot de passe et si la politique de mot de passe FoxIDs doit être appliquée avant l'appel au connector.

Lorsque la politique de mot de passe FoxIDs est activée, FoxIDs valide la longueur, la complexité et l'historique du mot de passe avant d'appeler le connector. Cela donne aux utilisateurs un retour immédiat de la politique FoxIDs, mais AD reste l'autorité et peut encore rejeter un mot de passe avec password_not_accepted à cause d'une longueur minimale, de la complexité, de l'historique des mots de passe, d'un minimum password age, d'une fine-grained password policy ou d'un custom password filter.

Paramètres FoxIDs Directory Connector pour Active Directory

L'API URL dans FoxIDs doit pointer vers le base URL du connector. FoxIDs ajoute les noms d'endpoint lorsqu'il appelle le connector.

Par défaut, seule la connexion avec une adresse e-mail est activée dans Login authentication method. Si les utilisateurs doivent pouvoir se connecter avec un nom d'utilisateur ou un numéro de téléphone, activez les identifiants utilisateur correspondants dans Login authentication method.

L'exemple ci-dessous active à la fois le nom d'utilisateur et l'e-mail.

Identifiants utilisateur FoxIDs Login authentication method pour Directory Connector

Patching et mises à jour

Téléchargez la nouvelle release FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip et consultez les release notes.
Décompressez le zip dans un dossier temporaire et copiez-y les fichiers appsettings*.json actuels, ou conservez les secrets dans les variables d'environnement IIS.
Arrêtez le site IIS ou l'application pool.
Renommez ou copiez le dossier actuel dans un dossier de sauvegarde, par exemple C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
Copiez les nouveaux fichiers avec Xcopy dans C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory et vérifiez les autorisations NTFS pour l'identité de l'application pool.
Démarrez l'application pool et vérifiez GET /health, puis testez une connexion Directory Connector ou une opération sur le mot de passe.
Si un rollback est nécessaire, arrêtez l'application pool, restaurez le dossier de sauvegarde vers le chemin actif et redémarrez l'application pool.

Le web.config par défaut écrit les logs stdout d'ASP.NET Core dans C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Gardez le stdout logging activé jusqu'à ce que le connector soit vérifié, puis envisagez de le désactiver ou de transférer les logs vers le système de logs normal de l'environnement après validation en production.