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.

Utilisez Directory Connector lorsque :

  • vous voulez que les utilisateurs se connectent avec la méthode d’authentification login normale.
  • 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 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.
  • 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 n’appelle les endpoints du cycle de vie du mot de passe que lorsque l’utilisateur interne est connu et possède un directoryUserId. Cela empêche FoxIDs d’appeler l’annuaire externe sans la liaison stable avec l’utilisateur externe.

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.

L’API dispose d’une URL de base et de trois endpoints :

  • authentication valide le mot de passe actuel d’un utilisateur.
  • 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/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.

Requête de changement de mot de passe

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

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

Champs :

  • directoryUserId est envoyé et doit être utilisé comme liaison stable avec l’annuaire.
  • 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,
  "disableAccount": false,
  "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 optionnels individuellement, mais au moins l’un d’eux doit être présent. FoxIDs enregistre les valeurs renvoyées comme identifiants de l’utilisateur interne.
  • 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é.
  • disableAccount contrôle si l’utilisateur interne est désactivé dans FoxIDs après synchronisation.
  • 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 la combinaison nom d’utilisateur / mot de passe est rejetée par l’endpoint authentication, retournez le code HTTP 400, 401 ou 403 et invalid_username_password.

{
  "error": "invalid_username_password",
  "errorMessage": "Invalid username or 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.

Codes d’erreur pris en charge :

  • invalid_username_password - La combinaison identifiant utilisateur / mot de passe a été rejetée par l’annuaire.
  • invalid_current_password - Le mot de passe actuel dans une requête de changement de mot de passe a été rejeté par l’annuaire.
  • user_disabled - L’utilisateur existe dans l’annuaire mais est désactivé. FoxIDs désactivera l’utilisateur interne.
  • user_deleted - L’utilisateur n’existe plus ou est supprimé dans l’annuaire. FoxIDs supprimera l’utilisateur interne.
  • password_not_accepted - Le nouveau mot de passe a été rejeté par une règle de mot de passe de l’annuaire qui ne correspond pas à un code plus spécifique.
  • password_min_length - Le nouveau mot de passe est plus court que la longueur minimale du mot de passe dans l’annuaire.
  • password_max_length - Le nouveau mot de passe est plus long que la longueur maximale du mot de passe dans l’annuaire.
  • password_banned_characters - Le nouveau mot de passe contient un ou plusieurs caractères ou mots rejetés par l’annuaire.
  • password_complexity - Le nouveau mot de passe ne satisfait pas aux exigences de complexité de l’annuaire.
  • password_email_text_complexity - Le nouveau mot de passe contient l’e-mail de l’utilisateur ou une partie de celui-ci.
  • password_phone_text_complexity - Le nouveau mot de passe contient le numéro de téléphone de l’utilisateur ou une partie de celui-ci.
  • password_username_text_complexity - Le nouveau mot de passe contient le nom d’utilisateur de l’utilisateur ou une partie de celui-ci.
  • password_url_text_complexity - Le nouveau mot de passe contient du texte lié à l’URL FoxIDs.
  • password_risk - Le nouveau mot de passe est connu comme risqué, compromis ou autrement non sûr.
  • password_history - Le nouveau mot de passe a été rejeté parce qu’il a déjà été utilisé auparavant.
  • password_expired - Le mot de passe actuel est expiré et doit être changé avant de poursuivre l’authentification.
  • new_password_equals_current - Le nouveau mot de passe est identique au mot de passe actuel.

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