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

Cuando un usuario inicia sesión con nombre de usuario y contraseña, FoxIDs llama a la API de Directory Connector.

Tras una validación correcta, FoxIDs crea o actualiza el usuario interno en el entorno según la respuesta de la API. La respuesta debe incluir un directoryUserId estable, que se almacena en el usuario interno y se utiliza para vincular el usuario de FoxIDs con el usuario del directorio externo.

El directoryUserId no es un identificador de usuario conocido por el usuario final. Es un ID independiente y estable del directorio externo. No use correo electrónico, teléfono ni nombre de usuario como directoryUserId porque esos valores pueden cambiar. El valor debe ser estable y único en el directorio externo.

Si FoxIDs ya conoce el directoryUserId del usuario interno, se envía en la solicitud de Directory Connector junto con exactamente uno de los identificadores del usuario: correo electrónico, teléfono o nombre de usuario. Esto permite que el directorio externo identifique al usuario incluso si ha cambiado un identificador.

Si la API de Directory Connector valida correctamente al usuario, FoxIDs actualiza el usuario interno con los identificadores, las propiedades seleccionadas y los claims devueltos por la API.

Si el conector informa que el usuario está deshabilitado o eliminado, FoxIDs deshabilitará o eliminará al usuario interno en el entorno.

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

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.
  • Login create-user flow calls the create-user endpoint.
  • 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.

FoxIDs normalmente solo llama a los endpoints del ciclo de vida de la contraseña cuando el usuario interno es conocido y tiene un directoryUserId. La excepción es change-password durante el primer inicio de sesión, cuando el directorio externo ha devuelto password_expired antes de que FoxIDs haya creado el usuario interno. En ese caso FoxIDs envía el identificador de inicio de sesión y la contraseña actual sin directoryUserId; después de un cambio de contraseña correcto, FoxIDs usa la respuesta correcta para crear el usuario interno y guardar el directoryUserId devuelto.

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.

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.

The API has a base URL and four endpoints:

  • authentication valida la contraseña actual de un usuario.
  • create-user creates a new user in the external directory and returns the created user.
  • 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/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 de solicitud Accept-Language, por ejemplo Accept-Language: da-DK. En un flujo de inicio de sesión, corresponde al idioma seleccionado mediante ui_locales o el navegador, con el inglés como idioma de reserva en FoxIDs. La API puede utilizar esta cabecera para localizar los mensajes destinados al usuario y debe elegir su propio idioma de reserva si no admite el idioma solicitado. Esta cabecera se envía a los cuatro endpoints.

Solicitud de autenticación

El endpoint authentication recibe la contraseña del usuario y exactamente un identificador de usuario. FoxIDs envía directoryUserId si el usuario interno existe y el valor es conocido.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "testpass1"
}

Campos:

  • directoryUserId es opcional. FoxIDs lo envía cuando el usuario interno existe y el valor es conocido.
  • Se envía exactamente uno de email, phone o username.
  • password es obligatorio.

FoxIDs selecciona el identificador a partir de la entrada de inicio de sesión del usuario y de la configuración de identificadores habilitados. Por ejemplo, si solo está habilitado el nombre de usuario y el usuario introduce user1@somewhere.org, FoxIDs lo envía como username. FoxIDs elimina los espacios en blanco circundantes antes de enviar el nombre de usuario al connector.

Create-user request

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 los campos 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.

Si la operación se realiza correctamente, devuelva una respuesta de éxito normal. FoxIDs guarda el directoryUserId devuelto en el usuario interno creado después de crear el usuario en el directorio externo.

Solicitud de cambio de contraseña

El endpoint change-password recibe exactamente un identificador de usuario, la contraseña actual y la nueva contraseña. FoxIDs envía directoryUserId cuando el usuario interno existe y el valor es conocido.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Campos:

  • directoryUserId es opcional. FoxIDs lo envía cuando el usuario interno existe y el valor es conocido. Puede omitirse durante el primer inicio de sesión si el directorio externo requiere un cambio de contraseña antes de que FoxIDs haya creado el usuario interno.
  • Se envía exactamente uno de email, phone o username.
  • currentPassword y newPassword son obligatorios.

Solicitud de establecer contraseña

El endpoint set-password recibe la vinculación estable del usuario con el directorio, exactamente un identificador de usuario y una nueva contraseña.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "newpass1"
}

Campos:

  • directoryUserId se envía y debe usarse como la vinculación estable con el directorio.
  • Se envía exactamente uno de email, phone o username. FoxIDs selecciona el primer identificador interno disponible en este orden: correo electrónico, teléfono, nombre de usuario.
  • password es obligatorio.

Respuesta de éxito

En caso de éxito, la API debe devolver el código HTTP 200 y una respuesta de usuario.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "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.
  • 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.

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.

Respuesta de error

Si se rechaza la autenticación Basic, devuelva el código HTTP 401 y invalid_api_id_secret.

{
  "error": "invalid_api_id_secret",
  "errorMessage": "Invalid API ID or secret."
}

Si el usuario no existe al llamar al endpoint authentication sin un directoryUserId, devuelva el código HTTP 400, 401 o 403 y user_not_exists.

{
  "error": "user_not_exists",
  "errorMessage": "User not found."
}

Si la contraseña es rechazada por el endpoint authentication, devuelva el código HTTP 400, 401 o 403 y invalid_password.

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

Si el identificador de usuario y la contraseña son válidos, pero el inicio de sesión se rechaza por otro motivo, devuelva el código de estado HTTP 400, 401 o 403 y login_rejected desde authentication. Se admite tanto con directoryUserId como sin él. El campo opcional uiErrorMessage se muestra como texto sin formato en el formulario de inicio de sesión. La API proporciona el mensaje traducido a partir de 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 caracteres de espacio en blanco, FoxIDs muestra el mismo mensaje genérico de inicio de sesión localizado que para invalid_password, user_not_exists, user_disabled y user_deleted. Un inicio de sesión rechazado se contabiliza en la protección existente contra intentos de inicio de sesión fallidos repetidos. No crea, actualiza, deshabilita ni elimina al usuario interno.

Si la contraseña actual es rechazada por el endpoint change-password, devuelva el código HTTP 400, 401 o 403 y invalid_current_password.

{
  "error": "invalid_current_password",
  "errorMessage": "Invalid current password."
}

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.

FoxIDs muestra un uiErrorMessage devuelto solo para login_rejected. Para otros códigos de error admitidos, FoxIDs selecciona el mensaje destinado al usuario de sus propios recursos de texto localizados. El texto de diagnóstico de errorMessage nunca se utiliza como alternativa a un mensaje destinado al usuario.

Códigos de error admitidos por endpoint:

Código de error authentication create-user change-password set-password Significado
invalid_api_id_secret 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 Sí No No Ya existe un usuario con el identificador proporcionado en el directorio externo.
user_not_exists Sí, sin directoryUserId No Sí, sin directoryUserId No Ningún usuario del directorio externo coincide con los identificadores de usuario proporcionados.
invalid_password Sí No No No El directorio ha rechazado la contraseña de una solicitud de autenticación.
login_rejected 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 Sí No El directorio ha rechazado la contraseña actual de una solicitud de cambio de contraseña.
create_user_not_supported No Sí No No El conector no admite la creación de usuarios en el directorio externo.
user_disabled Sí No Sí Sí El usuario existe en el directorio, pero está deshabilitado. FoxIDs deshabilita al usuario interno.
user_deleted Sí, con directoryUserId No Sí, con directoryUserId Sí, con directoryUserId El usuario del directorio externo vinculado mediante directoryUserId ya no existe o ha sido eliminado. FoxIDs elimina al usuario interno.
password_not_accepted 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 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 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 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 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 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 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 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 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 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 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 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 Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece ha sido rechazada porque ya se ha utilizado anteriormente.
password_expired Sí Sí Sí Sí La contraseña que se valida, se utiliza para crear un usuario, se cambia o se establece ha caducado y debe cambiarse antes de que pueda continuar la autenticación.
new_password_equals_current 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.

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 un código de error admitido por el endpoint y el directoryUserId proporcionado, según lo indicado anteriormente. Un código no admitido, una respuesta con formato incorrecto o un estado HTTP inesperado constituye un fallo de integración y conduce a la página de error genérica. En caso de fallo técnico en el conector, devuelva el código HTTP 500. Consulte Resolución de errores del navegador para encontrar los detalles de diagnóstico mediante 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, user_not_exists, user_disabled o user_deleted 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 un usuario no puede iniciar sesión mediante este flujo de inicio de sesión por cualquier motivo, valide primero el identificador de usuario y la contraseña proporcionados. Devuelva un rechazo basado en esta restricción solo después de verificar ambos correctamente, para que la restricción no revele si un identificador adivinado pertenece a un usuario real. Devuelva login_rejected desde authentication, indique la razón de diagnóstico en errorMessage y, si procede, proporcione instrucciones seguras para el usuario en uiErrorMessage. Si no se pueden verificar las credenciales, devuelva el fallo de autenticación habitual sin revelar la restricción.

FoxIDs depende de que el conector verifique las credenciales antes de devolver login_rejected; una búsqueda de cuenta correcta o el conocimiento de directoryUserId no son suficientes. Antes de verificar las credenciales, muestre las instrucciones o los botones para métodos de inicio de sesión alternativos con independencia de si el identificador proporcionado coincide con una cuenta.

Utilice user_disabled y user_deleted únicamente para informar del estado correspondiente de la cuenta en el directorio. También deshabilitan o eliminan al usuario interno y revocan su acceso; no son códigos genéricos para rechazar el inicio de sesión.

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.

El ejemplo incluye:

  • los endpoints authentication, create-user, change-password y set-password.
  • HTTP Basic authentication con el nombre de usuario de API directory_connector.
  • un pequeño directorio en memoria con usuarios de demostración y valores estables de directoryUserId.
  • ejemplos de errores de política de contraseñas como password_min_length, password_banned_characters y new_password_equals_current.
  • un ejemplo de usuario deshabilitado que devuelve user_disabled.

La colección de Postman directory-connector-api.postman_collection.json puede utilizarse para llamar y probar la API de ejemplo con Postman.

Componente de Active Directory

FoxIDs incluye un componente Directory Connector para Active Directory desplegable en IIS. El componente implementa la API de Directory Connector para un dominio AD/LDAP y puede validar contraseñas, cambiar contraseñas, establecer contraseñas, devolver atributos de AD configurados como claims y devolver pertenencias anidadas configuradas a grupos de AD como claims.

Configurar

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

  1. Seleccione la pestaña Settings.
  2. Seleccione la pestaña Environment.
  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