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.

Use Directory Connector cuando:

  • quiera que los usuarios inicien sesión con el método de autenticación login normal.
  • 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 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.
  • 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 solo llama a los endpoints del ciclo de vida de la contraseña cuando el usuario interno es conocido y tiene un directoryUserId. Esto evita que FoxIDs llame al directorio externo sin la vinculación estable con el usuario externo.

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.

La API tiene una URL base y tres endpoints:

  • authentication valida la contraseña actual de un usuario.
  • 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/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.

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.

Solicitud de cambio de contraseña

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

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "currentPassword": "oldpass1",
  "newPassword": "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.
  • 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,
  "disableAccount": false,
  "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 debe estar presente al menos uno. FoxIDs guarda los valores devueltos como identificadores del usuario interno.
  • 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.
  • disableAccount controla si el usuario interno se deshabilita en FoxIDs después de la sincronización.
  • 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.

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 la combinación de nombre de usuario y contraseña es rechazada por el endpoint authentication, devuelva el código HTTP 400, 401 o 403 y invalid_username_password.

{
  "error": "invalid_username_password",
  "errorMessage": "Invalid username or password."
}

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 es registrado por FoxIDs y no se muestra al usuario final.

Códigos de error compatibles:

  • invalid_username_password - La combinación de identificador de usuario y contraseña fue rechazada por el directorio.
  • invalid_current_password - La contraseña actual en una solicitud de cambio de contraseña fue rechazada por el directorio.
  • user_disabled - El usuario existe en el directorio, pero está deshabilitado. FoxIDs deshabilitará al usuario interno.
  • user_deleted - El usuario ya no existe o ha sido eliminado del directorio. FoxIDs eliminará al usuario interno.
  • password_not_accepted - La nueva contraseña fue rechazada por una regla de contraseña del directorio que no corresponde a un código más específico.
  • password_min_length - La nueva contraseña es más corta que la longitud mínima del directorio.
  • password_max_length - La nueva contraseña es más larga que la longitud máxima del directorio.
  • password_banned_characters - La nueva contraseña contiene uno o varios caracteres o palabras rechazados por el directorio.
  • password_complexity - La nueva contraseña no cumple los requisitos de complejidad del directorio.
  • password_email_text_complexity - La nueva contraseña contiene el correo electrónico del usuario o parte de él.
  • password_phone_text_complexity - La nueva contraseña contiene el número de teléfono del usuario o parte de él.
  • password_username_text_complexity - La nueva contraseña contiene el nombre de usuario del usuario o parte de él.
  • password_url_text_complexity - La nueva contraseña contiene texto relacionado con la URL de FoxIDs.
  • password_risk - La nueva contraseña es conocida como riesgosa, comprometida o insegura de otro modo.
  • password_history - La nueva contraseña fue rechazada porque ya se había usado antes.
  • password_expired - La contraseña actual ha caducado y debe cambiarse antes de continuar con la autenticación.
  • new_password_equals_current - La nueva contraseña es la misma que 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.

Si se producen otros errores, devuelva el código HTTP 500 u otro código de error adecuado. Incluya un errorMessage técnico cuando sea útil para el diagnóstico.

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, 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 Active Directory Directory Connector 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

Tu privacidad

Tu privacidad

Usamos cookies para mejorar tu experiencia en nuestros sitios web. Haz clic en «Aceptar todas las cookies» para aceptar su uso. Para rechazar cookies no esenciales, haz clic en «Solo cookies necesarias».

Visita nuestra política de privacidad para saber más