Directory Connector

Directory Connector permite que FoxIDs use un directorio externo como fuente autoritativa para las contraseñas de los usuarios internos y determinados datos de usuario.

Los usuarios siguen existiendo como usuarios internos en el entorno de FoxIDs. Durante la autenticación por contraseña y las operaciones del ciclo de vida de la contraseña, FoxIDs llama a la API de Directory Connector en lugar de validar la contraseña solo contra el usuario interno de FoxIDs.

Como FoxIDs mantiene un registro interno del usuario, se puede añadir la gestión de autenticación multi-factor (MFA) de FoxIDs a los usuarios del repositorio externo. El connector puede devolver configuraciones de usuario relacionadas con MFA, como requireMultiFactor y métodos de two-factor deshabilitados, y FoxIDs aplica esas configuraciones al usuario interno mientras el repositorio externo sigue siendo autoritativo para contraseñas y determinados datos de usuario.

Para Active Directory, FoxIDs incluye un componente Directory Connector para Active Directory desplegable en IIS.

Use Directory Connector cuando:

  • quiera que los usuarios inicien sesión con el método de autenticación login normal.
  • quiera habilitar usuarios de un directorio existente para aplicaciones OpenID Connect y SAML 2.0 a través de FoxIDs.
  • su directorio externo sea autoritativo para la validación y el cambio de contraseñas.
  • quiera que FoxIDs mantenga un registro interno del usuario con identificadores, propiedades, claims, configuraciones de autenticación multi-factor (MFA), asignaciones de acceso y, opcionalmente, una copia local de la contraseña.
  • quiera una vía para cambiar más adelante a usuarios internos y validación de contraseñas en FoxIDs sin obligar a todos los usuarios a pasar por un restablecimiento de contraseña.

Hay un Directory Connector por entorno. Cuando está habilitado, se aplica a nivel de entorno.

Cómo funciona

FoxIDs sincroniza bajo demanda cuando un usuario introduce un identificador en un flujo de inicio de sesión o recuperación. Llama a synchronise-user antes de comprobar la cuenta, crea un usuario FoxIDs si es necesario y actualiza los identificadores, propiedades y claims administrados por el directorio.

La sincronización forma parte de la activación de Directory Connector. FoxIDs sincroniza al inicio del acceso, la recuperación y las comprobaciones de cuentas de sesiones existentes, y cuando se utiliza un refresh token para una cuenta vinculada al directorio. Las continuaciones con códigos de confirmación, MFA y Extended UI utilizan la cuenta seleccionada y las comprobaciones habituales de FoxIDs. Si la sincronización falla, el flujo se detiene.

La respuesta debe incluir un directoryUserId estable y único. Utilice el ID permanente de la cuenta del directorio en lugar del correo electrónico, teléfono o nombre de usuario. Este vínculo permite a FoxIDs encontrar la misma cuenta después de cambiar los identificadores. Se conservan las aplicaciones de autenticación registradas y las asignaciones de acceso de FoxIDs.

Cuando el usuario introduce un identificador, FoxIDs envía solo ese correo, teléfono o nombre de usuario. Para reutilizar sesiones y procesar solicitudes con refresh tokens, FoxIDs carga el usuario asociado y sincroniza mediante el ID de directorio almacenado en él. Las operaciones de contraseña también utilizan el ID de directorio del usuario cargado. No se almacena por separado en la secuencia de inicio de sesión.

El conector devuelve todos los datos actuales del usuario. FoxIDs sustituye los identificadores, propiedades y claims administrados por el directorio, incluidos el estado de deshabilitación, los requisitos de cambio de contraseña y la configuración inicial de contraseñas. Aplica las mismas comprobaciones de cuenta, recuperación y MFA que a los usuarios internos. Los usuarios internos sin vínculo con el directorio no se sincronizan ni se vinculan automáticamente.

Una respuesta de sincronización con disableAccount: true deshabilita al usuario FoxIDs y revoca sus sesiones activas y refresh-token grants. Si el conector devuelve el código user_deleted al sincronizar por ID de directorio, FoxIDs elimina al usuario interno y revoca sus sesiones activas y refresh tokens. Si una búsqueda solo por identificador no encuentra ninguna cuenta, FoxIDs comprueba cualquier vínculo existente con el directorio antes de continuar, para que los datos locales obsoletos no permitan iniciar sesión ni recuperar la cuenta. El código user_not_exists por sí solo no elimina cuentas.

Las solicitudes con refresh tokens comprueban tanto la cuenta original como una cuenta local usada mediante suplantación, si están vinculadas al directorio. Si la sincronización descubre una cuenta deshabilitada o eliminada, FoxIDs revoca sus sesiones activas y refresh-token grants y rechaza la renovación actual. La comprobación normal de sesiones activas valida el estado de sesión de FoxIDs; no contacta por sí misma con el directorio. Una aplicación que valida localmente un access token emitido atiende a su caducidad, no a la revocación de la sesión en FoxIDs.

Los cambios se reflejan en la siguiente comprobación de cuenta bajo demanda. No existe un proceso de sincronización en segundo plano.

Directory Connector puede utilizarse como integración permanente, gestionando usuarios y contraseñas en el directorio externo, o para migrarlos gradualmente a FoxIDs. Durante la migración, mantenga el conector activado mientras se crean los usuarios y habilite la copia local de contraseña para guardar las contraseñas tras autenticaciones, cambios o restablecimientos correctos mediante FoxIDs.

Una vez finalizada la migración, desactive Directory Connector y administre usuarios y contraseñas directamente en FoxIDs. Antes del cambio, cree los usuarios aún no aprovisionados y organice la configuración o recuperación de contraseña para quienes no tengan una copia local actualizada. La copia refleja la última autenticación, modificación o restablecimiento correcto mediante FoxIDs; no incluye los cambios posteriores realizados únicamente en el directorio externo.

Protección de las búsquedas

Cuando un usuario introduce un correo, teléfono o nombre de usuario en la interfaz de acceso o recuperación, la búsqueda en el directorio cuenta para un límite compartido por todos los identificadores de la secuencia actual. Se utilizan los ajustes del entorno Failed login attempt limit, duración del contador y periodo de observación. Cuentan tanto las búsquedas correctas como las llamadas fallidas; una autenticación de contraseña correcta no reinicia este contador. Al alcanzar el límite, debe esperarse el periodo de observación o iniciarse una nueva secuencia. La sincronización para reutilizar sesiones y las solicitudes con refresh tokens no usan este contador. La protección de contraseñas y códigos de confirmación mantiene sus contadores independientes existentes.

Identificadores de inicio de sesión y vinculación con el directorio

Los usuarios pueden iniciar sesión con su correo, teléfono o nombre de usuario actual según los tipos activados en el método de inicio de sesión. Antes de autenticar la contraseña, el identificador introducido debe coincidir con uno actual devuelto por el conector. FoxIDs elimina los espacios alrededor de la entrada. El correo y el nombre de usuario se comparan sin distinguir mayúsculas de minúsculas. Los teléfonos usan el formato internacional requerido.

Inicio de sesión tras cambiar los identificadores

Cuando se introduce un identificador, FoxIDs sincroniza correo, teléfono y nombre de usuario desde el directorio. El ID estable mantiene la misma cuenta FoxIDs aunque cambie uno o todos los identificadores. Se conservan las aplicaciones de autenticación registradas y las asignaciones de acceso; siguen aplicándose las restricciones y requisitos MFA existentes.

Situación Qué ocurre durante la sincronización
El usuario inicia sesión con un nombre de usuario sin cambios, mientras su correo o teléfono ha cambiado en el directorio. FoxIDs actualiza la misma cuenta con los identificadores actuales del conector.
El usuario inicia sesión con un identificador nuevo que FoxIDs aún no conoce. Si el directorio devuelve el identificador nuevo y el mismo ID estable, el usuario continúa con su cuenta FoxIDs existente. También funciona si han cambiado todos los identificadores.
El usuario inicia sesión con un identificador antiguo que el conector ya no devuelve. Se rechaza el acceso con el error habitual, aunque todavía conozca la contraseña. Debe utilizar un identificador actual de un tipo activado.
El conector deja de devolver un correo, teléfono o nombre de usuario. Ese identificador se elimina de la cuenta FoxIDs durante la sincronización. El conector debe devolver al menos uno actual.

Por ejemplo, un usuario cuyo correo cambia de old@example.org a new@example.org puede iniciar sesión con new@example.org antes de que FoxIDs conozca esa dirección. El conector debe devolver new@example.org y el ID de directorio sin cambios. El usuario conserva la cuenta y sus aplicaciones de autenticación registradas. También puede utilizar un nombre de usuario sin cambios si esta opción está activada.

El conector debe devolver todos los identificadores actuales que FoxIDs deba conservar. Los valores omitidos o vacíos se tratan como identificadores eliminados; los anteriores no se mantienen como alias de acceso. Solo pueden utilizarse tipos de identificador activados en el método de inicio de sesión.

Conflictos de cuentas

Cada usuario del directorio debe tener un ID estable y único; sus identificadores no pueden pertenecer a otra cuenta FoxIDs. FoxIDs busca primero el identificador en el directorio y utiliza el ID devuelto para encontrar o crear la cuenta local. Si guardar los identificadores genera un conflicto con otra cuenta, el flujo se detiene. Un administrador debe corregir la configuración del directorio o de la cuenta FoxIDs; las cuentas no se fusionan ni reasignan automáticamente.

Un usuario interno existente sin vínculo con el directorio no puede iniciar sesión mediante Directory Connector. Activarlo no vincula automáticamente una cuenta a un usuario del directorio solo porque coincidan el correo, teléfono o nombre de usuario.

Copia local de la contraseña

El directorio externo es autoritativo mientras Directory Connector está habilitado. FoxIDs no recurre al hash local de la contraseña si la API de Directory Connector no está disponible temporalmente.

De forma predeterminada, FoxIDs guarda una copia local de la contraseña en el usuario interno después de una validación correcta de contraseña mediante el conector o de una operación del ciclo de vida de la contraseña. Esto puede deshabilitarse en la configuración del entorno.

La copia local de la contraseña no se utiliza mientras Directory Connector está habilitado. Existe para facilitar un cambio posterior a usuarios internos y validación de contraseñas en FoxIDs sin obligar a todos los usuarios a restablecer su contraseña.

Ciclo de vida de la contraseña

La creación de usuarios y las operaciones del ciclo de vida de la contraseña se delegan a la API de Directory Connector:

  • La autenticación por contraseña llama al endpoint authentication.
  • La creación de usuarios durante el inicio de sesión llama al endpoint create-user.
  • El cambio de contraseña del usuario llama al endpoint change-password.
  • Los flujos de establecer contraseña y restablecer contraseña llaman al endpoint set-password.

Los endpoints de contraseña reciben el directoryUserId estable del usuario cargado. El directorio comprueba el estado actual de la cuenta y las credenciales durante la operación. La autenticación, el cambio y el restablecimiento devuelven éxito o error. La creación de usuarios devuelve el ID de directorio de la cuenta creada, que FoxIDs usa para una sincronización independiente.

Las operaciones de contraseña usan el ID de directorio almacenado en el usuario FoxIDs cargado. El conector comprueba el estado y las credenciales o autorización de restablecimiento necesarias, ejecuta la acción y devuelve éxito o error. Los identificadores, atributos y claims solo se devuelven mediante sincronización.

Tras cambiar o restablecer correctamente la contraseña, FoxIDs registra la hora actual del cambio y elimina los requisitos de cambiar o definir una contraseña. También guarda una copia local si está configurado. La secuencia activa continúa con la gestión habitual de cuenta, recuperación y MFA de FoxIDs.

Si falla una acción o FoxIDs no puede guardar los cambios conocidos de contraseña, el flujo se detiene. Un cambio ya aceptado por el directorio no se revierte y FoxIDs no repite automáticamente la acción tras un tiempo de espera agotado o una respuesta fallida. La siguiente sincronización actualiza la cuenta local.

Con Enable password policy activado, FoxIDs verifica la contraseña actual del directorio antes de comprobar la nueva. Esto puede requerir una llamada adicional a autenticación antes de change-password.

FoxIDs no actualiza su historial interno de contraseñas cuando se usa Directory Connector, porque FoxIDs no conoce necesariamente todos los cambios de contraseña realizados en el directorio externo.

Configuración y recuperación de contraseñas

En el primer inicio de sesión, un usuario del directorio puede definir una contraseña con un código de confirmación por correo o SMS, porque la ha olvidado o porque debe elegir una nueva.

Para usar Forgot your password?, introduzca un identificador actual del directorio de un tipo activado en el método de acceso. FoxIDs sincroniza y crea la cuenta antes de enviar el código. La recuperación por correo o SMS debe estar activada y el usuario debe acceder al contacto de recuperación actual devuelto por el directorio.

Tras verificar el código y enviar una contraseña nueva, FoxIDs llama a set-password con el ID estable. Devuelva setPasswordEmail o setPasswordSms y el identificador de contacto correspondiente para exigir este flujo de configuración. FoxIDs utiliza su flujo habitual para definir contraseñas.

Los códigos de confirmación están vinculados a la cuenta para la que se emitieron. Las cuentas gestionadas mediante un conector de directorio usan la misma verificación que otros usuarios internos. FoxIDs mantiene la gestión habitual de errores de recuperación sin mostrar diagnósticos del conector.

Política de contraseñas y mensajes de error

El directorio externo aplica la política de contraseñas. FoxIDs usa la política de contraseñas del entorno cuando muestra mensajes de error de política de contraseñas devueltos por el conector.

Configure la política de contraseñas del entorno para que coincida con la política de contraseñas del directorio externo. Si no coinciden, los usuarios pueden ver indicaciones de contraseña que no reflejan los requisitos reales del directorio externo.

Por ejemplo, si el directorio externo rechaza una contraseña porque es demasiado corta, FoxIDs usa la longitud mínima de contraseña del entorno al mostrar el mensaje de error.

Implementar API

Usted implementa una API de Directory Connector y configura FoxIDs con su URL base y secreto.

La API tiene una URL base y cinco endpoints:

  • synchronise-user busca un usuario y devuelve el estado actual de su cuenta, sus identificadores y claims.
  • authentication valida la contraseña actual de un usuario.
  • create-user crea un usuario en el directorio externo y devuelve su ID permanente.
  • change-password valida la contraseña actual y la cambia por una nueva.
  • set-password establece una nueva contraseña sin validar la contraseña actual.

Si la URL base es https://somewhere.org/directory, los endpoints son:

  • https://somewhere.org/directory/synchronise-user
  • https://somewhere.org/directory/authentication
  • https://somewhere.org/directory/create-user
  • https://somewhere.org/directory/change-password
  • https://somewhere.org/directory/set-password

FoxIDs Cloud llama a su API desde la IP 57.128.60.142. Las IP pueden cambiar o ampliarse.

Seguridad

Las solicitudes están protegidas con HTTP Basic authentication:

  • Nombre de usuario: directory_connector
  • Contraseña: el secreto de API configurado

La llamada es HTTP POST con un cuerpo JSON.

FoxIDs envía el idioma seleccionado en la cabecera Accept-Language, por ejemplo Accept-Language: da-DK. En el acceso sigue el idioma seleccionado mediante ui_locales o el navegador, con inglés como alternativa de FoxIDs. La API puede utilizar esta cabecera para traducir mensajes y debe elegir su propia alternativa si no admite el idioma solicitado. La cabecera se envía a los cinco endpoints.

Solicitud de sincronización

El endpoint synchronise-user recibe un identificador de usuario o un ID de directorio conocido. La primera búsqueda en el acceso o recuperación usa el identificador introducido. FoxIDs utiliza el directoryUserId guardado para comprobar sesiones existentes y solicitudes con refresh tokens, y el ID devuelto después de create-user.

Una búsqueda inicial por correo:

{
  "email": "user1@somewhere.org"
}

Una comprobación posterior de la cuenta:

{
  "directoryUserId": "a1b2c3d4"
}

Utilice directoryUserId como clave de búsqueda autoritativa cuando esté presente. De lo contrario, busque exactamente uno de email, phone o username. Devuelva HTTP 200 con todos los datos del usuario, también para cuentas deshabilitadas. Devuelva user_deleted si falta el ID conocido y user_not_exists si una búsqueda solo por identificador no encuentra ninguna cuenta. Un identificador proporcionado nunca prueba la propiedad de una cuenta.

FoxIDs elige el identificador de la solicitud según los tipos de acceso activados. Si solo está habilitado el nombre de usuario, una entrada con formato de correo se envía como username. Se eliminan los espacios alrededor. La entrada debe coincidir con un identificador actual de un tipo activado en la respuesta; el campo supuesto de la solicitud no limita qué campo de respuesta puede coincidir.

Para errores, consulte Respuesta de error.

Respuesta correcta

El endpoint synchronise-user devuelve HTTP 200 con todos los datos actuales del usuario. Si la solicitud incluye un ID de directorio, la respuesta debe contener el mismo. FoxIDs lo verifica antes de guardar datos. Se rechazan HTTP 204 y los datos incompletos.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "disableAccount": false,
  "changePassword": false,
  "setPasswordEmail": false,
  "setPasswordSms": false,
  "disableSetPasswordEmail": false,
  "disableSetPasswordSms": false,
  "passwordLastChanged": 1760000000,
  "emailVerified": true,
  "phoneVerified": true,
  "disableTwoFactorApp": false,
  "disableTwoFactorSms": false,
  "disableTwoFactorEmail": false,
  "requireMultiFactor": false,
  "claims": [
    { "type": "name", "value": "User One" },
    { "type": "role", "value": "employee" }
  ]
}

FoxIDs utiliza la respuesta para crear o actualizar el usuario interno en el entorno.

Campos:

  • directoryUserId es obligatorio. Debe ser estable y único en el directorio externo y se almacena en el usuario interno de FoxIDs.
  • email, phone y username son opcionales individualmente, pero al menos uno debe estar presente. FoxIDs almacena los valores devueltos como identificadores del usuario interno. Los valores de identificador de usuario devueltos deben identificar de forma única a un solo usuario en el directorio externo usado por el connector.
  • phone debe incluir el código de país en formato internacional, por ejemplo +4511223344.
  • confirmAccount controla si FoxIDs debe ejecutar un flujo de confirmación para confirmar al usuario interno.
  • disableAccount controla la deshabilitación directa de la cuenta. El paso a deshabilitada revoca las sesiones FoxIDs y refresh-token grants del usuario.
  • changePassword exige cambiar la contraseña tras verificar correctamente las credenciales.
  • setPasswordEmail y setPasswordSms exigen definir una contraseña mediante el flujo de código correspondiente. Debe existir el identificador de contacto y estar activado el método de recuperación.
  • disableSetPasswordEmail y disableSetPasswordSms desactivan los métodos de recuperación correspondientes.
  • passwordLastChanged es una marca de tiempo Unix opcional no negativa, en segundos. Si se proporciona al sincronizar, actualiza la antigüedad de contraseña usada por FoxIDs. Si se omite, se conserva la marca existente. Un cambio o restablecimiento correcto registra la hora actual en FoxIDs; una sincronización posterior puede aportar la marca autoritativa del directorio.
  • emailVerified controla si el correo electrónico del usuario interno se marca como verificado.
  • phoneVerified controla si el número de teléfono del usuario interno se marca como verificado.
  • disableTwoFactorApp deshabilita la autenticación de dos factores con aplicación autenticadora para el usuario interno.
  • disableTwoFactorSms deshabilita la autenticación de dos factores por SMS para el usuario interno.
  • disableTwoFactorEmail deshabilita la autenticación de dos factores por correo electrónico para el usuario interno.
  • requireMultiFactor controla si el usuario interno debe usar autenticación multi-factor.
  • claims es opcional. FoxIDs almacena los claims devueltos en el usuario interno.

Los claims admiten un valueType opcional: String, Boolean, Number, JsonObject o JsonArray. El campo value permanece como texto; omita valueType para String. FoxIDs conserva el tipo seleccionado y registra una advertencia antes de recurrir al texto para un valor no válido. Consulte tipos de valores de claims para ver ejemplos y los límites numéricos. La misma representación se utiliza para los claims enviados en las solicitudes de creación de usuarios y devueltos en las respuestas de sincronización.

FoxIDs ignora los claims cuyo type o value falta, es null, está vacío o solo contiene espacios en blanco. Con el registro de trazas de mensajes activado, la traza de la respuesta incluye los claims recibidos antes de filtrarlos. Los mensajes de traza largos se truncan.

Los claims protegidos, como sid y auth_time, también se descartan de las respuestas de sincronización.

Solicitud de autenticación

El endpoint authentication recibe el ID estable obligatorio del directorio y la contraseña actual.

{
  "directoryUserId": "a1b2c3d4",
  "password": "testpass1"
}

Compruebe el estado actual de la cuenta y la contraseña antes de devolver éxito. Verifique la contraseña antes de proporcionar indicaciones de política específicas de la cuenta.

Para errores, consulte Respuesta de error.

Respuesta correcta

En caso de éxito, devuelva HTTP 204 sin cuerpo de respuesta.

Solicitud de creación de usuario

El endpoint create-user recibe exactamente un identificador de usuario, una contraseña obligatoria, las propiedades create-user seleccionadas y los claims recopilados durante el flujo create-user de FoxIDs.

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "confirmAccount": true,
  "requireMultiFactor": false,
  "claims": [
    { "type": "given_name", "value": "User" },
    { "type": "family_name", "value": "One" }
  ]
}

Campos:

  • Se envía exactamente uno de email, phone o username.
  • password es obligatorio. Crear usuario sin contraseña no se admite con Directory Connector porque la API de Directory Connector autentica a los usuarios con contraseña.
  • confirmAccount y requireMultiFactor son los ajustes solicitados para la creación del usuario en FoxIDs.
  • claims contiene las reclamaciones que no son identificadores y que se recopilan durante la creación del usuario en FoxIDs.

Para errores, consulte Respuesta de error.

Respuesta correcta

En caso de éxito, devuelva HTTP 200 con el ID permanente de la cuenta creada:

{
  "directoryUserId": "a1b2c3d4"
}

FoxIDs llama después a synchronise-user con este ID para obtener la cuenta completa y crear el usuario interno FoxIDs.

Solicitud de cambio de contraseña

El endpoint change-password recibe el ID de directorio obligatorio y las contraseñas actual y nueva. Verifique la actual antes de devolver indicaciones de política específicas de la cuenta.

{
  "directoryUserId": "a1b2c3d4",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Para errores, consulte Respuesta de error.

Respuesta correcta

En caso de éxito, devuelva HTTP 204 sin cuerpo. El cambio debe satisfacer el requisito de contraseña del directorio.

Solicitud de establecer contraseña

El endpoint set-password recibe el ID obligatorio del directorio y la contraseña nueva. FoxIDs lo llama tras autorizar el restablecimiento o la configuración, incluida la verificación de códigos en recuperación. El conector debe volver a comprobar el estado actual de la cuenta antes de cambiar la contraseña.

{
  "directoryUserId": "a1b2c3d4",
  "password": "newpass1"
}

Para errores, consulte Respuesta de error.

Respuesta correcta

En caso de éxito, devuelva HTTP 204 sin cuerpo. El restablecimiento o la configuración debe satisfacer el requisito de contraseña del directorio.

Respuesta de error

Todos los endpoints usan el mismo formato JSON de error. Devuelva un código admitido por el endpoint en error y detalles diagnósticos en errorMessage. Por ejemplo, una contraseña rechazada por authentication:

{
  "error": "invalid_password",
  "errorMessage": "Invalid password."
}

Utilice estos códigos de estado HTTP:

  • 401 con invalid_api_id_secret cuando se rechaza la autenticación HTTP Basic.
  • 400, 401 o 403 para los demás códigos admitidos de la tabla siguiente.
  • 500 para un fallo técnico del conector.

El campo errorMessage contiene texto de diagnóstico para los registros de FoxIDs y no se muestra al usuario final. Indique la causa del fallo, pero nunca incluya contraseñas, secretos de API ni claves privadas.

Solo authentication puede devolver login_rejected, tras verificar el identificador y la contraseña del usuario. Puede incluir un uiErrorMessage opcional que FoxIDs muestra como texto sin formato en el formulario de acceso. La API proporciona el mensaje en el idioma elegido mediante Accept-Language:

{
  "error": "login_rejected",
  "errorMessage": "Credentials verified; login rejected by directory policy.",
  "uiErrorMessage": "You cannot log in here. Contact support."
}

Si uiErrorMessage se omite, es null, está vacío o solo contiene espacios, FoxIDs muestra el mismo mensaje general localizado que para invalid_password y operation_rejected. Para otros códigos admitidos, FoxIDs ignora uiErrorMessage y elige el mensaje entre sus propios textos localizados. El diagnóstico de errorMessage nunca se usa como mensaje alternativo para el usuario. Consulte Errores de autenticación y privacidad para los requisitos de verificación.

Los errores de authentication, change-password y set-password no devuelven datos del usuario, no cambian la cuenta interna y no revocan sesiones ni refresh tokens existentes. La sincronización aplica los cambios de cuenta del directorio. Los intentos de autenticación y cambio rechazados siguen contando para el límite existente de accesos fallidos.

Códigos de error admitidos por endpoint:

Código de error synchronise-user authentication create-user change-password set-password Significado
invalid_api_id_secret Sí Sí Sí Sí Sí El nombre de usuario o el secreto de la API para HTTP Basic authentication no es válido.
user_exists No No Sí No No Ya existe un usuario con el identificador proporcionado en el directorio externo.
user_not_exists Sin ID de directorio No No No No Ningún usuario del directorio coincide con la búsqueda solo por identificador.
invalid_password No Sí No No No El directorio ha rechazado la contraseña de una solicitud de autenticación.
login_rejected No Sí No No No El inicio de sesión se rechazó después de verificar el identificador de usuario y la contraseña. Se muestra un uiErrorMessage opcional en el formulario de inicio de sesión.
invalid_current_password No No No Sí No El directorio ha rechazado la contraseña actual de una solicitud de cambio de contraseña.
create_user_not_supported No No Sí No No El conector no admite la creación de usuarios en el directorio externo.
operation_rejected No Sí No Sí Sí La operación no puede completarse, por ejemplo porque la cuenta no está disponible. FoxIDs registra errorMessage, ignora uiErrorMessage y muestra un error general localizado sin cambiar el estado de la cuenta.
user_deleted Con ID de directorio No No No No Un ID conocido ya no existe. FoxIDs revoca el acceso y elimina al usuario durante la sincronización.
password_not_accepted No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece ha sido rechazada por una regla de contraseñas del directorio que no corresponde a un código más específico.
password_min_length No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece es más corta que la longitud mínima de contraseña del directorio.
password_max_length No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece es más larga que la longitud máxima de contraseña del directorio.
password_banned_characters No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece contiene uno o más caracteres o palabras que el directorio rechaza.
password_complexity No Sí Sí Sí Sí Error de complejidad de caracteres heredado que FoxIDs interpreta como password_character_variation. Utilice uno de los dos códigos de error de caracteres específicos para las nuevas integraciones.
password_character_repeat No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece contiene demasiadas repeticiones de caracteres.
password_character_variation No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece no contiene suficiente variedad de caracteres.
password_email_text_complexity No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece contiene la dirección de correo electrónico del usuario o parte de ella.
password_phone_text_complexity No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece contiene el número de teléfono del usuario o parte de él.
password_username_text_complexity No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece contiene el nombre de usuario o parte de él.
password_url_text_complexity No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece contiene texto relacionado con la URL de FoxIDs.
password_risk No Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece es conocida por ser arriesgada, estar comprometida o ser insegura por otro motivo.
password_history No No No Sí Sí La contraseña nueva se rechazó porque ya se había utilizado.
password_expired No Sí No No No La contraseña proporcionada se verificó pero ha caducado; el usuario debe cambiarla antes de continuar la autenticación.
new_password_equals_current No No No Sí No La nueva contraseña es igual a la actual. set-password no puede devolver este error porque no recibe la contraseña actual.

Si FoxIDs debe comprobar su política antes de cambiar una contraseña, primero llama a authentication para verificar la actual. Si el conector devuelve password_expired desde esa autenticación, el cambio puede continuar. El endpoint change-password debe aceptar una contraseña actual caducada pero verificada y devolver solo errores admitidos para el cambio.

En los errores de política de contraseñas, FoxIDs usa la política de contraseñas del entorno para mostrar el mensaje de error orientado al usuario. Consulte Política de contraseñas y mensajes de error.

Devuelva únicamente códigos admitidos por el endpoint y el directoryUserId proporcionado, según la tabla. Un código no admitido, respuesta mal formada o estado HTTP inesperado supone un fallo de integración y conduce a la página de error general. Consulte Resolución de errores del navegador para localizar los diagnósticos con los identificadores de la página de error.

Errores de autenticación y privacidad de los usuarios

Un solicitante no autenticado no debe poder determinar si existe un nombre de usuario o una dirección de correo electrónico a partir de un fallo de inicio de sesión. Durante la autenticación con contraseña, FoxIDs gestiona los errores admitidos de la siguiente manera:

Error del conector Resultado para el usuario
invalid_password, operation_rejected o una cuenta no disponible detectada durante la sincronización El mismo mensaje genérico de inicio de sesión, como Correo electrónico o contraseña incorrectos., traducido al idioma activo y adaptado a los identificadores de inicio de sesión habilitados.
login_rejected El uiErrorMessage proporcionado, o el mismo mensaje genérico de inicio de sesión si falta o está vacío, en el mismo lugar del formulario de inicio de sesión.
password_not_accepted La página de cambio de contraseña con indicaciones generales sobre la política de contraseñas.
password_expired u otro error específico de la política de contraseñas La página de cambio de contraseña con las indicaciones localizadas correspondientes a la política de contraseñas.

El conector debe verificar la contraseña actual proporcionada antes de devolver un error de política de contraseñas desde authentication. De lo contrario, una página o un mensaje diferente puede permitir que un atacante descubra usuarios y confirme sus identificadores probando nombres de usuario o direcciones de correo electrónico. En change-password, verifique la contraseña actual antes de devolver indicaciones específicas de la cuenta sobre la nueva contraseña. Las comprobaciones generales de formato no deben revelar si existe una cuenta.

Si por cualquier motivo un usuario no puede usar este flujo de acceso, valide primero su identificador y contraseña. Rechace por esta restricción solo después de verificar ambos, para no revelar si un identificador adivinado pertenece a un usuario real. Devuelva login_rejected desde authentication, indique la razón diagnóstica en errorMessage y, opcionalmente, información segura en uiErrorMessage. Si no se pueden verificar las credenciales, devuelva el fallo habitual sin revelar la restricción.

FoxIDs confía en que el conector verifique las credenciales antes de devolver login_rejected; una búsqueda correcta o conocer directoryUserId no es suficiente. Antes de verificarlas, muestre instrucciones o botones de métodos alternativos independientemente de que el identificador corresponda a una cuenta.

Solo synchronise-user informa del estado de cuenta: devuelva todos los datos con disableAccount: true para una cuenta deshabilitada, o user_deleted cuando un ID conocido ya no exista. Los endpoints de contraseña devuelven operation_rejected si la cuenta no está disponible. A diferencia de login_rejected, no exige una contraseña verificada porque nunca aporta información específica de la cuenta al navegador.

Gestione los fallos de forma coherente para identificadores conocidos y desconocidos, incluidos los tiempos de respuesta observables y la protección frente a intentos repetidos. Un mensaje genérico por sí solo no impide descubrir usuarios si una redirección, un estado o un tiempo de respuesta diferente revela el resultado. Siga las directrices de OWASP sobre errores de autenticación al implementar el conector.

Ejemplo de API

El ejemplo DirectoryConnectorApiSample muestra cómo implementar la API de Directory Connector en ASP.NET Core.

Las implementaciones y clientes de prueba deben seguir los contratos anteriores: HTTP 200 con todos los datos del usuario para synchronise-user, HTTP 200 con el ID creado para create-user y HTTP 204 sin cuerpo para operaciones de contraseña correctas.

Componente de Active Directory

FoxIDs incluye un Directory Connector para Active Directory desplegable en IIS. Implementa la API para un dominio AD/LDAP y permite sincronizar cuentas, validar, cambiar y definir contraseñas, y devolver atributos AD y pertenencias a grupos anidados configuradas como claims.

Configurar

Configure Directory Connector en la configuración del entorno en FoxIDs Control Client.

  1. Selecciona la pestaña Configuración.
  2. Selecciona la pestaña Entorno.
  3. Busque la sección Directory Connector.
  4. Habilite Directory Connector.
  5. Agregue la URL base de la API sin la carpeta del endpoint en API URL.
  6. Agregue el API secret.
  7. Decida si desea guardar una copia local de la contraseña.
  8. Configure la política de contraseñas del entorno para que coincida con la política de contraseñas del directorio externo.
  9. Haga clic en Update.

Configuración de Directory Connector