Active Directory Directory Connector

Active Directory Directory Connector es un componente de FoxIDs que implementa la API Directory Connector para un dominio AD/LDAP.

Instale el componente en el entorno Windows del cliente, donde pueda llegar a los controladores de dominio. FoxIDs llama al componente por HTTPS, y el componente valida usuarios, cambia contraseñas, establece contraseñas y devuelve propiedades de usuario y claims desde Active Directory.

El connector se instala y configura en el servidor Windows/IIS cercano a Active Directory. En FoxIDs se habilita después en el entorno bajo Settings > Environment > Directory connector settings, donde se configura la API URL y el secret del connector.

El componente se publica como un zip de Windows junto con versiones de FoxIDs:

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

Endpoints

El componente expone:

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

El endpoint /health no está autenticado y solo devuelve un estado mínimo. Comprueba la configuración requerida, el bind AD, el acceso a user search-base y el acceso opcional a group search-base. No comprueba permisos delegados para set-password / password reset. Los errores detallados y los stack traces se registran en el servidor y no se devuelven desde el endpoint.

Respuesta de ejemplo:

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

La respuesta solo contiene status, adBind, userSearch y groupSearch. status es ok solo cuando la configuración requerida es válida, el bind AD se realiza correctamente, el acceso a user search-base funciona y el acceso a group search-base no ha fallado. groupSearch es not_configured cuando no hay ninguna group search base configurada. Si una comprobación no puede ejecutarse porque una comprobación anterior falló o falta configuración, el campo se devuelve como unknown.

Requisitos

• Windows Server con IIS.
• ASP.NET Core Hosting Bundle para .NET 10.
• Acceso de red desde el servidor IIS al controlador de dominio configurado.
• LDAPS u otro canal seguro para operaciones de contraseña.
• Un dominio AD por despliegue del connector.
• Una cuenta de servicio de dominio si se usan credentials configuradas.
• Permiso AD delegado de password reset si set-password debe estar soportado.

Se recomienda un servidor IIS unido al dominio con el application pool ejecutándose como cuenta de servicio de dominio. Las bind-credentials configuradas también se admiten mediante appsettings.json o variables de entorno.

Autenticación

Configure una clave API fuerte en appsettings.json. FoxIDs envía HTTP Basic authentication con API ID directory_connector y el secret configurado.

Use el encabezado X-FoxIDs-Api-Key: <api-key> solo si un reverse proxy delante de Directory Connector gestiona Basic authentication antes de que la solicitud llegue al componente y reescribe api-key.

Búsqueda y bind en AD

El componente busca primero en AD con la identidad de servicio configurada. Soporta búsqueda por:

• correo electrónico
• teléfono
• nombre de usuario
• directoryUserId cuando FoxIDs ya lo conoce

El usuario se identifica en FoxIDs con el AD objectGUID codificado como base64. El valor se devuelve como directoryUserId y permanece estable aunque cambie el correo, teléfono o nombre de usuario.

Para autenticación con contraseña, el componente encuentra el distinguished name del usuario y después hace bind a AD como ese usuario con la contraseña enviada. Esto evita búsquedas ambiguas de usuarios y soporta todos los tipos de identificador configurados.

Para el cambio de contraseña, AD valida la contraseña actual y la política de contraseñas.

Si la política de contraseñas de FoxIDs está habilitada para Directory Connector, FoxIDs pre-valida la longitud, la complejidad y el historial de contraseñas antes de llamar al connector. Esto ofrece al usuario feedback más preciso para esas comprobaciones. AD sigue siendo autoritativo y aún puede rechazar la contraseña después con password_not_accepted, por ejemplo por longitud mínima, complejidad, historial de contraseñas, minimum password age, fine-grained password policy o un custom password filter.

Para set-password, la identidad de servicio configurada debe tener derechos delegados de reset-password.

Acceso de la cuenta de servicio AD

El connector debe ejecutarse con una identidad de servicio AD dedicada. No convierta esta identidad en administrador de dominio. Use un usuario de dominio normal o un grupo de seguridad dedicado, y delegue solo los permisos necesarios en las OU que usa el connector.

Para la búsqueda de usuarios y la autenticación, la identidad del connector debe tener permiso para buscar en cada OU configurada en UserSearchBases y leer los objetos de usuario y atributos usados por el connector. Una nueva identidad de servicio AD dedicada a menudo ya tiene este acceso de lectura de forma predeterminada, salvo que las ACL de AD se hayan restringido.

Para la autenticación con contraseña, el connector primero encuentra al usuario con la identidad de servicio y después hace bind a AD como ese usuario con la contraseña enviada. Esto no requiere que la identidad de servicio conozca o restablezca la contraseña del usuario.

Para el cambio de contraseña, cuando el usuario proporciona la contraseña actual, el connector usa el comportamiento AD de password change y AD valida la contraseña actual y la política de contraseñas.

Para set-password / password reset, delegue derechos de password reset sobre los objetos de usuario en cada OU configurada en UserSearchBases donde el connector deba admitir password reset. En Active Directory Users and Computers, haga clic con el botón derecho en la user OU usada por el connector, seleccione Delegate Control..., seleccione la identidad del connector y, en el paso Tasks to Delegate, seleccione Reset user passwords and force password change at next logon.

Delegue también cualquier permiso adicional relacionado con contraseñas que exija la política del dominio, solo si el entorno usa esas operaciones. Para claims de rol de grupo, la identidad del connector necesita acceso de lectura a los GroupSearchBases configurados. Debe poder listar la group OU y leer atributos de grupo como cn, distinguishedName y member.

Configuración

La configuración usa la configuración estándar de .NET. Los valores se pueden definir en appsettings.json, variables de entorno, configuración de IIS u otro provider de configuración .NET.

Ejemplo:

{
	"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 siempre se mapea desde el objectGUID de AD y se devuelve codificado en base64. No es configurable.

UserIdentifiers controla qué atributos de AD se pueden usar para búsqueda por correo electrónico, teléfono y nombre de usuario y se devuelven como identificadores de usuario de nivel superior. Al menos uno de Email, Phone o Username debe estar configurado y ser devuelto desde AD para obtener una respuesta válida del connector. Quite un mapping de identificador si ese campo no debe usarse para búsqueda ni devolverse en el nivel superior. El mismo atributo de AD aún puede configurarse como claim en Claims.

Ajustes importantes:

• ApiKey: secret compartido que FoxIDs usa para autenticarse con el connector. FoxIDs lo envía como HTTP Basic authentication con API ID directory_connector. Use un valor fuerte y único y guárdelo como variable de entorno o configuración de IIS siempre que sea posible.
• ActiveDirectory:Domain: nombre del dominio AD, por ejemplo example.local.
• ActiveDirectory:Server: controlador de dominio o endpoint LDAP opcional. Si se omite, se usa Domain.
• ActiveDirectory:Port: puerto LDAP. Use 636 para LDAPS.
• ActiveDirectory:UseSsl: habilita LDAPS. Manténgalo habilitado para operaciones de contraseña salvo que se garantice otro canal seguro.
• ActiveDirectory:Bind:Mode: Integrated usa la identidad del application pool de IIS o la identidad del proceso. ConfiguredCredentials usa los valores configurados de Username y Password.
• ActiveDirectory:Bind:Username y ActiveDirectory:Bind:Password: las credentials se usan solo cuando Mode es ConfiguredCredentials. Para la contraseña, prefiera variables de entorno o configuración de IIS.
• ActiveDirectory:UserSearchBases: uno o varios distinguished names donde se buscan usuarios, por ejemplo OU=Users,DC=example,DC=local.
• ActiveDirectory:GroupSearchBases: uno o varios distinguished names donde se buscan grupos de roles configurados.
• ActiveDirectory:UserIdentifiers: atributos AD opcionales para lookup e identificadores de usuario de nivel superior: Email, Phone y Username. Configure al menos uno.
• ActiveDirectory:Claims: atributos de usuario devueltos como claims, por ejemplo name, given_name, family_name o email.
• ActiveDirectory:GroupClaims: pertenencia a grupos AD devuelta como claims, normalmente claims role. Consulte Claims de grupo para conocer los detalles de configuración.

Claims de grupo

Los claims de grupo están deshabilitados por defecto. Para habilitarlos, agregue una o más entradas a ActiveDirectory:GroupClaims.

Cada entrada de GroupClaims define el tipo de claim que se devolverá y qué pertenencias a grupos AD deben producir ese claim. Claim es obligatorio y normalmente es role.

Hay tres configuraciones habituales:

"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 no se configura ni GroupDistinguishedName ni GroupName, el connector busca en los GroupSearchBases configurados y devuelve un claim por cada grupo coincidente del que el usuario sea miembro. En este modo, no configure Value; el valor del claim debe provenir de ValueAttribute. Con ValueAttribute configurado por defecto como cn, un grupo llamado admin_access devuelve:

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

Use GroupDistinguishedName cuando conozca el DN exacto del grupo AD. Esto evita la búsqueda por nombre y es la opción más precisa.

Use GroupName cuando el connector deba encontrar un único grupo a partir de su valor cn en GroupSearchBases. La búsqueda debe coincidir con exactamente un grupo. Si existe más de un grupo con el mismo cn en los GroupSearchBases configurados, la solicitud falla porque el mapeo del grupo es ambiguo.

Use Value solo cuando GroupDistinguishedName o GroupName estén configurados y el claim devuelto deba tener un valor fijo independiente del nombre del grupo AD. Por ejemplo, un grupo con DN CN=Employees,OU=Groups,DC=example,DC=local puede devolver el valor de role employees.

Si Value no está configurado, el connector lee el ValueAttribute configurado del grupo AD coincidente. El ValueAttribute predeterminado es cn, lo que devuelve el nombre del grupo AD como valor del claim. Configure otro atributo de grupo solo si ese atributo existe en el objeto de grupo y contiene el valor que debe enviarse a FoxIDs.

IncludeNestedGroups controla cómo se comprueba la pertenencia:

• true usa la regla de coincidencia recursiva de AD, por lo que el claim se devuelve si el usuario es miembro directo o lo es a través de grupos anidados.
• false comprueba solo la pertenencia directa al grupo coincidente.

Instalación en IIS

El componente se despliega con Xcopy. No tiene base de datos ni instalador. La actualización o el rollback se realizan reemplazando los archivos de la carpeta del sitio IIS y manteniendo la configuración específica del entorno.

1. Instale ASP.NET Core Hosting Bundle para .NET 10 (descarga directa) en el servidor Windows.
2. Cree una carpeta, por ejemplo C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
3. Descomprima el zip de release en la carpeta.
4. Configure appsettings.json o variables de entorno.
5. Cree un application pool de IIS.
6. Configure la identidad del application pool como cuenta de servicio de dominio, o configure bind-credentials en appsettings.json.
7. Cree un sitio IIS o una aplicación IIS que apunte a la carpeta.
8. Enlace el sitio a HTTPS.
9. Cree la carpeta de logs C:\inetpub\logs\LogFiles\foxids-ad y conceda acceso de escritura a la identidad del grupo de aplicaciones. Por ejemplo, si el grupo de aplicaciones de IIS se llama FoxIDs.DirectoryConnector.AD, conceda acceso de escritura a IIS AppPool\FoxIDs.DirectoryConnector.AD.
10. Verifique GET /health.

Para la API URL de FoxIDs, use la base URL del connector, por ejemplo:

https://connector.example.com

FoxIDs añade authentication, change-password y set-password a esa base URL.

Certificado TLS

FoxIDs llama al connector por HTTPS, por lo que el sitio IIS debe tener un certificado TLS de confianza. Puede usar su propio certificado o crear opcionalmente un certificado gratuito de Let's Encrypt con win-acme.

Con win-acme, descargue la última release win-acme.v2.x.x.x64.pluggable.zip, descomprímala en una carpeta permanente, ejecute wacs.exe desde una Command Prompt elevada y seleccione el sitio IIS que hospeda Directory Connector. Win-acme agrega el enlace HTTPS y registra la renovación automática del certificado en Windows Task Scheduler.

Consulte el flujo completo en FoxIDs Windows / IIS HTTP and HTTPS guide.

Configuración del entorno FoxIDs

Cuando el connector esté instalado y accesible por HTTPS, habilítelo en el entorno FoxIDs:

1. Abra FoxIDs Control Client.
2. Seleccione el tenant y el entorno que deben usar el connector.
3. Vaya a Settings > Environment.
4. Busque Directory connector settings.
5. Habilite directory connector.
6. Introduzca la API URL del connector, por ejemplo https://connector.example.com.
7. Introduzca el mismo secret que el ApiKey del connector.
8. Elija si FoxIDs debe guardar una copia local de la contraseña y si la política de contraseñas de FoxIDs debe aplicarse antes de llamar al connector.

Cuando la política de contraseñas de FoxIDs está habilitada, FoxIDs valida la longitud, la complejidad y el historial de contraseñas antes de llamar al connector. Esto ofrece a los usuarios feedback inmediato de la política de FoxIDs, pero AD sigue siendo autoritativo y aún puede rechazar una contraseña con password_not_accepted por longitud mínima, complejidad, historial de contraseñas, minimum password age, fine-grained password policy o un custom password filter.

La API URL de FoxIDs debe apuntar a la base URL del connector. FoxIDs agrega los nombres de los endpoints cuando llama al connector.

De forma predeterminada, en Login authentication method solo está habilitado el inicio de sesión con dirección de correo electrónico. Si los usuarios deben poder iniciar sesión con nombre de usuario o número de teléfono, habilite los identificadores de usuario correspondientes en Login authentication method.

El ejemplo siguiente tiene habilitados tanto el nombre de usuario como el correo electrónico.

Parcheo y actualizaciones

1. Descargue la nueva release FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip y revise las release notes.
2. Descomprima el zip en una carpeta temporal y copie los archivos actuales appsettings*.json, o mantenga los secrets en variables de entorno de IIS.
3. Detenga el sitio IIS o el application pool.
4. Cambie el nombre de la carpeta actual o cópiela a una carpeta de respaldo, por ejemplo C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
5. Copie los archivos nuevos con Xcopy en C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory y verifique los permisos NTFS para la identidad del application pool.
6. Inicie el application pool y verifique GET /health; después pruebe un inicio de sesión mediante Directory Connector o una operación de contraseña.
7. Si se necesita rollback, detenga el application pool, restaure la carpeta de respaldo en la ruta activa y vuelva a iniciar el application pool.

El web.config predeterminado escribe logs stdout de ASP.NET Core en C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Mantenga stdout logging habilitado hasta que el connector esté verificado y considere deshabilitarlo o reenviar los logs al sistema normal de logs del entorno después de la validación en producción.

Documentación relacionada

• Directory Connector
• Usuarios internos
• Despliegue de FoxIDs en Windows / IIS