Directory Connector

Directory Connector permet à FoxIDs d’utiliser un annuaire externe comme source faisant autorité pour les mots de passe des utilisateurs internes et certaines données utilisateur.

Les utilisateurs existent toujours comme utilisateurs internes dans l’environnement FoxIDs. Lors de l’authentification par mot de passe et des opérations du cycle de vie du mot de passe, FoxIDs appelle l’API Directory Connector au lieu de valider le mot de passe uniquement par rapport à l’utilisateur interne FoxIDs.

Comme FoxIDs conserve une fiche utilisateur interne, la gestion de l’authentification multifacteur (MFA) de FoxIDs peut être ajoutée aux utilisateurs du référentiel externe. Le connector peut retourner des paramètres utilisateur liés à la MFA, tels que requireMultiFactor et des méthodes two-factor désactivées, et FoxIDs applique ces paramètres à l’utilisateur interne tandis que le référentiel externe reste l’autorité pour les mots de passe et certaines données utilisateur.

Pour Active Directory, FoxIDs inclut un composant Directory Connector pour Active Directory déployable sur IIS.

Utilisez Directory Connector lorsque :

  • vous voulez que les utilisateurs se connectent avec la méthode d’authentification login normale.
  • vous voulez activer des utilisateurs d’un annuaire existant pour des applications OpenID Connect et SAML 2.0 via FoxIDs.
  • votre annuaire externe fait autorité pour la validation et les changements de mot de passe.
  • vous voulez que FoxIDs conserve une fiche utilisateur interne avec identifiants, propriétés, claims, paramètres d’authentification multifacteur (MFA), attributions d’accès et, éventuellement, une copie locale du mot de passe.
  • vous voulez une voie pour passer plus tard aux utilisateurs internes et à la validation des mots de passe dans FoxIDs sans imposer à tous les utilisateurs une réinitialisation du mot de passe.

Il existe un Directory Connector par environnement. Lorsqu’il est activé, il s’applique au niveau de l’environnement.

Fonctionnement

Lorsqu’un utilisateur se connecte avec un nom d’utilisateur et un mot de passe, FoxIDs appelle l’API Directory Connector.

En cas de validation réussie, FoxIDs crée ou met à jour l’utilisateur interne dans l’environnement en fonction de la réponse de l’API. La réponse doit inclure un directoryUserId stable, stocké sur l’utilisateur interne et utilisé pour lier l’utilisateur FoxIDs à l’utilisateur de l’annuaire externe.

Le directoryUserId n’est pas un identifiant utilisateur connu de l’utilisateur final. Il s’agit d’un ID distinct et stable de l’annuaire externe. N’utilisez pas l’e-mail, le téléphone ni le nom d’utilisateur comme directoryUserId, car ces valeurs peuvent changer. La valeur doit être stable et unique dans l’annuaire externe.

Si FoxIDs connaît déjà le directoryUserId de l’utilisateur interne, il est envoyé dans la requête Directory Connector avec exactement un des identifiants de l’utilisateur : e-mail, téléphone ou nom d’utilisateur. Cela permet à l’annuaire externe d’identifier l’utilisateur même si un identifiant a changé.

Si l’API Directory Connector valide l’utilisateur avec succès, FoxIDs met à jour l’utilisateur interne avec les identifiants, les propriétés sélectionnées et les claims renvoyés par l’API.

Si le connecteur signale que l’utilisateur est désactivé ou supprimé, FoxIDs désactive ou supprime l’utilisateur interne dans l’environnement.

Copie locale du mot de passe

L’annuaire externe fait autorité tant que Directory Connector est activé. FoxIDs ne revient pas au hash local du mot de passe si l’API Directory Connector est temporairement indisponible.

Par défaut, FoxIDs enregistre une copie locale du mot de passe sur l’utilisateur interne après une validation de mot de passe réussie via le connecteur ou après une opération du cycle de vie du mot de passe. Cela peut être désactivé dans les paramètres de l’environnement.

La copie locale du mot de passe n’est pas utilisée tant que Directory Connector est activé. Elle existe pour permettre un basculement ultérieur vers des utilisateurs internes et une validation des mots de passe dans FoxIDs sans obliger tous les utilisateurs à réinitialiser leur mot de passe.

Cycle de vie du mot de passe

Les opérations du cycle de vie du mot de passe sont déléguées à l’API Directory Connector :

  • L’authentification par mot de passe appelle l’endpoint authentication.
  • Login create-user flow calls the create-user endpoint.
  • Le changement du mot de passe utilisateur appelle l’endpoint change-password.
  • Les flux de définition et de réinitialisation du mot de passe appellent l’endpoint set-password.

FoxIDs appelle normalement les endpoints du cycle de vie du mot de passe uniquement lorsque l’utilisateur interne est connu et possède un directoryUserId. L’exception est change-password lors de la première connexion, lorsque l’annuaire externe a renvoyé password_expired avant que FoxIDs ait créé l’utilisateur interne. Dans ce cas, FoxIDs envoie l’identifiant de connexion et le mot de passe actuel sans directoryUserId ; après un changement de mot de passe réussi, FoxIDs utilise la réponse de succès pour créer l’utilisateur interne et enregistrer le directoryUserId renvoyé.

FoxIDs ne met pas à jour son historique interne des mots de passe lorsque Directory Connector est utilisé, car FoxIDs ne connaît pas nécessairement tous les changements de mot de passe effectués dans l’annuaire externe.

Politique de mot de passe et messages d’erreur

L’annuaire externe applique la politique de mot de passe. FoxIDs utilise la politique de mot de passe de l’environnement lorsqu’il affiche les messages d’erreur de politique de mot de passe renvoyés par le connecteur.

Configurez la politique de mot de passe de l’environnement pour qu’elle corresponde à celle de l’annuaire externe. Si elles ne correspondent pas, les utilisateurs peuvent voir des indications de mot de passe qui ne reflètent pas les exigences réelles de l’annuaire externe.

Par exemple, si l’annuaire externe rejette un mot de passe parce qu’il est trop court, FoxIDs utilise la longueur minimale du mot de passe de l’environnement lorsqu’il rend le message d’erreur.

Implémenter l’API

Vous implémentez une API Directory Connector et configurez FoxIDs avec son URL de base et son secret.

The API has a base URL and four endpoints:

  • authentication valide le mot de passe actuel d’un utilisateur.
  • create-user creates a new user in the external directory and returns the created user.
  • change-password valide le mot de passe actuel et le remplace par un nouveau mot de passe.
  • set-password définit un nouveau mot de passe sans valider le mot de passe actuel.

Si l’URL de base est https://somewhere.org/directory, les endpoints sont :

  • 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 appelle votre API depuis l’IP 57.128.60.142.
Les IP peuvent changer ou être étendues.

Sécurité

Les requêtes sont sécurisées avec HTTP Basic authentication :

  • Nom d’utilisateur : directory_connector
  • Mot de passe : le secret API configuré

L’appel est un HTTP POST avec un corps JSON.

Requête d’authentification

L’endpoint authentication reçoit le mot de passe de l’utilisateur et exactement un identifiant utilisateur. FoxIDs envoie directoryUserId si l’utilisateur interne existe et que la valeur est connue.

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

Champs :

  • directoryUserId est optionnel. FoxIDs l’envoie lorsque l’utilisateur interne existe et que la valeur est connue.
  • Exactement un de email, phone ou username est envoyé.
  • password est requis.

FoxIDs sélectionne l’identifiant à partir de la saisie de connexion de l’utilisateur et des paramètres d’identifiant activés. Par exemple, si seul le nom d’utilisateur est activé et que l’utilisateur saisit user1@somewhere.org, FoxIDs l’envoie comme username.

Create-user request

L’endpoint create-user reçoit exactement un identifiant utilisateur, un mot de passe requis, les propriétés create-user sélectionnées et les claims collectés pendant le flux create-user 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 est requis. Créer un utilisateur sans mot de passe n’est pas pris en charge avec Directory Connector, car l’API Directory Connector authentifie les utilisateurs avec un mot de passe.
  • 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.

Requête de changement de mot de passe

L’endpoint change-password reçoit exactement un identifiant utilisateur, le mot de passe actuel et le nouveau mot de passe. FoxIDs envoie directoryUserId lorsque l’utilisateur interne existe et que la valeur est connue.

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

Champs :

  • directoryUserId est facultatif. FoxIDs l’envoie lorsque l’utilisateur interne existe et que la valeur est connue. Il peut être omis lors de la première connexion si l’annuaire externe exige un changement de mot de passe avant que FoxIDs ait créé l’utilisateur interne.
  • Exactement un de email, phone ou username est envoyé.
  • currentPassword et newPassword sont requis.

Requête de définition du mot de passe

L’endpoint set-password reçoit la liaison stable de l’utilisateur avec l’annuaire, exactement un identifiant utilisateur et un nouveau mot de passe.

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

Champs :

  • directoryUserId est envoyé et doit être utilisé comme liaison stable avec l’annuaire.
  • Exactement un de email, phone ou username est envoyé. FoxIDs sélectionne le premier identifiant utilisateur interne disponible dans cet ordre : e-mail, téléphone, nom d’utilisateur.
  • password est requis.

Réponse de succès

En cas de succès, l’API doit retourner le code HTTP 200 et une réponse utilisateur.

{
  "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 utilise la réponse pour créer ou mettre à jour l’utilisateur interne dans l’environnement.

Champs :

  • directoryUserId est requis. Il doit être stable et unique dans l’annuaire externe et est stocké sur l’utilisateur interne FoxIDs.
  • email, phone et username sont facultatifs individuellement, mais au moins l’un d’eux doit être présent. FoxIDs stocke les valeurs retournées comme identifiants de l’utilisateur interne. Les valeurs d’identifiant utilisateur retournées doivent identifier de façon unique un seul utilisateur dans l’annuaire externe utilisé par le connector.
  • phone doit inclure l’indicatif pays au format international, par exemple +4511223344.
  • confirmAccount contrôle si FoxIDs doit exécuter un flux de confirmation pour confirmer l’utilisateur interne.
  • emailVerified contrôle si l’e-mail de l’utilisateur interne est marqué comme vérifié.
  • phoneVerified contrôle si le numéro de téléphone de l’utilisateur interne est marqué comme vérifié.
  • disableTwoFactorApp désactive l’authentification à deux facteurs par application d’authentification pour l’utilisateur interne.
  • disableTwoFactorSms désactive l’authentification à deux facteurs par SMS pour l’utilisateur interne.
  • disableTwoFactorEmail désactive l’authentification à deux facteurs par e-mail pour l’utilisateur interne.
  • requireMultiFactor contrôle si l’utilisateur interne doit utiliser l’authentification multi-facteur.
  • claims est optionnel. FoxIDs enregistre les claims renvoyés sur l’utilisateur interne.

Réponse d’erreur

Si l’authentification Basic est rejetée, retournez le code HTTP 401 et invalid_api_id_secret.

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

Si l'utilisateur n'existe pas lors de l'appel à l'endpoint authentication, retournez le code HTTP 400, 401 ou 403 et user_not_exists.

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

Si le mot de passe est rejeté par l'endpoint authentication, retournez le code HTTP 400, 401 ou 403 et invalid_password.

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

Si le mot de passe actuel est rejeté par l’endpoint change-password, retournez le code HTTP 400, 401 ou 403 et invalid_current_password.

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

Le champ errorMessage est journalisé par FoxIDs et n’est pas montré à l’utilisateur 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.

Pour les erreurs de politique de mot de passe, FoxIDs utilise la politique de mot de passe de l’environnement pour afficher le message d’erreur destiné à l’utilisateur. Voir Politique de mot de passe et messages d’erreur.

Si d’autres erreurs surviennent, retournez le code HTTP 500 ou un autre code d’erreur approprié. Incluez un errorMessage technique lorsque c’est utile pour le diagnostic.

Exemple d’API

L’exemple DirectoryConnectorApiSample montre comment implémenter l’API Directory Connector en ASP.NET Core.

L’exemple inclut :

  • les endpoints authentication, create-user, change-password et set-password.
  • HTTP Basic authentication avec le nom d’utilisateur API directory_connector.
  • un petit annuaire en mémoire avec des utilisateurs de démonstration et des valeurs directoryUserId stables.
  • des exemples d’erreurs de politique de mot de passe telles que password_min_length, password_banned_characters et new_password_equals_current.
  • un exemple d’utilisateur désactivé qui renvoie user_disabled.

La collection Postman directory-connector-api.postman_collection.json peut être utilisée pour appeler et tester l’API d’exemple avec Postman.

Composant Active Directory

FoxIDs inclut un composant Directory Connector pour Active Directory déployable sur IIS. Le composant implémente l’API Directory Connector pour un domaine AD/LDAP et peut valider les mots de passe, changer les mots de passe, définir les mots de passe, retourner les attributs AD configurés sous forme de claims et retourner les appartenances imbriquées aux groupes AD configurées sous forme de claims.

Configurer

Configurez Directory Connector dans les paramètres de l’environnement du FoxIDs Control Client.

  1. Sélectionnez l’onglet Settings.
  2. Sélectionnez l’onglet Environment.
  3. Recherchez la section Directory Connector.
  4. Activez Directory Connector.
  5. Ajoutez l’URL de base de l’API sans le dossier de l’endpoint dans API URL.
  6. Ajoutez le API secret.
  7. Décidez si une copie locale du mot de passe doit être enregistrée.
  8. Configurez la politique de mot de passe de l’environnement pour qu’elle corresponde à celle de l’annuaire externe.
  9. Cliquez sur Update.

Paramètres de Directory Connector

Votre confidentialité

Votre confidentialité

Nous utilisons des cookies pour améliorer votre expérience sur nos sites. Cliquez sur « Accepter tous les cookies » pour accepter l'utilisation des cookies. Pour refuser les cookies non essentiels, cliquez sur « Cookies nécessaires uniquement ».

Consultez notre politique de confidentialité pour en savoir plus