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.

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.

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

Fields:

  • Exactly one of email, phone, or username is sent.
  • 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 and requireMultiFactor are the requested FoxIDs create-user settings.
  • claims contains the non-identifier claims collected during the FoxIDs create-user flow.

On success, return a normal success response. FoxIDs stores the returned directoryUserId on the internal user created after the external directory user has been created.

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.

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, 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 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.

Supported error codes by endpoint:

Error code authentication create-user change-password set-password Meaning
invalid_api_id_secret Yes Yes Yes Yes The HTTP Basic API username or secret is invalid.
user_exists No Yes No No A user with the supplied identifier already exists in the external directory.
user_not_exists Yes, without DirectoryUserId No Yes, without DirectoryUserId No No external directory user matched the supplied user identifiers.
invalid_password Yes No No No The password in an authentication request was rejected by the directory.
invalid_current_password No No Yes No The current password in a change-password request was rejected by the directory.
create_user_not_supported No Yes No No The connector does not support creating users in the external directory.
user_disabled Yes No Yes Yes The user exists in the directory but is disabled. FoxIDs will disable the internal user.
user_deleted Yes, with DirectoryUserId No Yes, with DirectoryUserId Yes, with DirectoryUserId The external directory user linked by DirectoryUserId no longer exists or is deleted. FoxIDs will delete the internal user.
password_not_accepted Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected by a directory password rule that does not map to a more specific code.
password_min_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is shorter than the directory password minimum length.
password_max_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is longer than the directory password maximum length.
password_banned_characters Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains one or more characters or words rejected by the directory.
password_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set does not satisfy the directory complexity requirements.
password_email_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's email or part of it.
password_phone_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's phone number or part of it.
password_username_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's username or part of it.
password_url_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains text related to the FoxIDs URL.
password_risk Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is known to be risky, compromised, or otherwise unsafe.
password_history Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected because it has been used before.
password_expired Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is expired and must be changed before authentication can continue.
new_password_equals_current No No Yes No The new password is the same as the current password. set-password cannot return this error because it does not receive the current password.

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, 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

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