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

FoxIDs synchronise à la demande lorsqu’un utilisateur saisit un identifiant dans un parcours de connexion ou de récupération. Il appelle synchronise-user avant de vérifier le compte, crée si nécessaire un utilisateur FoxIDs et met à jour les identifiants, propriétés et claims gérés par l’annuaire.

La synchronisation fait partie de l’activation de Directory Connector. FoxIDs synchronise au début de la connexion, de la récupération et des vérifications de compte lors de la réutilisation de sessions, ainsi que lorsqu’un refresh token est utilisé pour un compte lié à l’annuaire. Les étapes suivantes avec codes de confirmation, MFA et Extended UI utilisent le compte sélectionné et les vérifications FoxIDs habituelles. Un échec de synchronisation interrompt le parcours.

La réponse doit contenir un directoryUserId stable et unique. Utilisez l’ID permanent du compte dans l’annuaire plutôt qu’une adresse e-mail, un numéro de téléphone ou un nom d’utilisateur. Ce lien permet à FoxIDs de retrouver le même compte après une modification des identifiants. Les applications d’authentification enregistrées et les attributions d’accès FoxIDs sont conservées.

Lorsqu’un utilisateur saisit un identifiant, FoxIDs envoie uniquement cette adresse e-mail, ce numéro de téléphone ou ce nom d’utilisateur. Pour la réutilisation de sessions et les requêtes avec refresh token, FoxIDs charge l’utilisateur associé et synchronise à partir de l’ID d’annuaire enregistré sur celui-ci. Les opérations de mot de passe utilisent également l’ID d’annuaire de l’utilisateur chargé. Il n’est pas stocké séparément dans la séquence de connexion.

Le connecteur renvoie l’ensemble des données utilisateur actuelles. FoxIDs remplace les identifiants, propriétés et claims gérés par l’annuaire, y compris la désactivation du compte, les exigences de changement de mot de passe et les paramètres de définition initiale. Il applique les mêmes contrôles de compte, de récupération et de MFA que pour les utilisateurs internes. Les utilisateurs internes sans lien avec l’annuaire ne sont ni synchronisés ni associés automatiquement.

Une réponse de synchronisation avec disableAccount: true désactive l’utilisateur FoxIDs et révoque ses sessions actives et ses refresh-token grants. Si le connecteur renvoie le code d’erreur user_deleted lors d’une synchronisation par ID d’annuaire, FoxIDs supprime l’utilisateur interne et révoque ses sessions actives et refresh tokens. Si une recherche par identifiant seul ne trouve aucun compte, FoxIDs vérifie tout lien existant avec l’annuaire avant de poursuivre, afin que des données locales obsolètes ne permettent pas la connexion ou la récupération. Le code user_not_exists seul ne supprime pas un compte.

Les requêtes avec refresh token vérifient le compte d’origine ainsi que le compte local utilisé par usurpation d’identité, s’ils sont liés à l’annuaire. Si la synchronisation détecte un compte désactivé ou supprimé, FoxIDs révoque ses sessions actives et refresh-token grants et refuse le renouvellement en cours. Le contrôle ordinaire des sessions actives valide l’état de session FoxIDs ; il ne contacte pas lui-même l’annuaire. Une application validant localement un access token émis tient compte de son expiration plutôt que de la révocation de session dans FoxIDs.

Les modifications deviennent disponibles lors du prochain contrôle de compte à la demande. Il n’existe aucun processus de synchronisation en arrière-plan.

Directory Connector peut servir d’intégration permanente, avec gestion des utilisateurs et mots de passe dans l’annuaire externe, ou à migrer progressivement les utilisateurs vers FoxIDs. Pour une migration, laissez le connecteur activé pendant la création des utilisateurs et activez la copie locale du mot de passe afin de conserver les mots de passe après authentification, modification ou réinitialisation réussie via FoxIDs.

Une fois la migration terminée, désactivez Directory Connector et gérez directement utilisateurs et mots de passe dans FoxIDs. Avant le basculement, créez les utilisateurs non encore provisionnés et prévoyez la définition ou la récupération du mot de passe pour ceux sans copie locale actuelle. La copie reflète la dernière authentification, modification ou réinitialisation réussie via FoxIDs ; les changements ultérieurs effectués uniquement dans l’annuaire externe ne sont pas inclus.

Protection des recherches

Lorsqu’un utilisateur saisit une adresse e-mail, un numéro de téléphone ou un nom d’utilisateur dans l’interface de connexion ou de récupération, la recherche dans l’annuaire compte dans une limite commune à tous les identifiants saisis dans la séquence de connexion courante. Elle utilise les paramètres Failed login attempt limit, durée de vie du compteur et période d’observation de l’environnement. Les recherches réussies et les appels échoués comptent tous ; une authentification par mot de passe réussie ne remet pas ce compteur à zéro. À la limite, il faut attendre la période d’observation ou démarrer une nouvelle séquence. La synchronisation pour réutiliser une session ou traiter un refresh token n’utilise pas ce compteur. Les protections des mots de passe et codes de confirmation conservent leurs compteurs distincts existants.

Identifiants de connexion et liaison à l’annuaire

Les utilisateurs peuvent se connecter avec leur adresse e-mail, numéro de téléphone ou nom d’utilisateur actuel, selon les types activés sur la méthode de connexion. Avant l’authentification par mot de passe, la saisie doit correspondre à un identifiant actuel renvoyé par le connecteur. FoxIDs supprime les espaces périphériques. Les comparaisons d’e-mail et de nom d’utilisateur ignorent la casse. Les numéros de téléphone suivent le format international requis.

Connexion après modification des identifiants

Lorsqu’un identifiant est saisi, FoxIDs synchronise l’e-mail, le numéro de téléphone et le nom d’utilisateur depuis l’annuaire. L’ID d’annuaire stable maintient le lien avec le même compte FoxIDs, même si un ou tous les identifiants changent. Applications d’authentification enregistrées et attributions d’accès sont conservées ; les restrictions d’accès et exigences MFA existantes restent applicables.

Situation Comportement lors de la synchronisation
L’utilisateur se connecte avec un nom d’utilisateur inchangé, alors que son e-mail ou téléphone a changé dans l’annuaire. FoxIDs met à jour le même compte avec les identifiants actuels renvoyés par le connecteur.
L’utilisateur se connecte avec un nouvel identifiant que FoxIDs ne connaît pas encore. Si l’annuaire renvoie le nouvel identifiant et le même ID stable, l’utilisateur conserve son compte FoxIDs existant. Cela fonctionne aussi si tous ses identifiants ont changé.
L’utilisateur se connecte avec un ancien identifiant que le connecteur ne renvoie plus. La connexion est refusée avec l’erreur habituelle, même si le mot de passe est encore connu. L’utilisateur doit fournir un identifiant actuel d’un type activé.
Le connecteur cesse de renvoyer une adresse e-mail, un numéro de téléphone ou un nom d’utilisateur. Cet identifiant est supprimé du compte FoxIDs lors de la synchronisation. Le connecteur doit renvoyer au moins un identifiant actuel.

Par exemple, un utilisateur dont l’e-mail passe de old@example.org à new@example.org peut se connecter avec new@example.org avant que FoxIDs connaisse cette adresse. Le connecteur doit renvoyer new@example.org et l’ID d’annuaire inchangé. Le compte et les applications d’authentification enregistrées sont conservés. Un nom d’utilisateur inchangé peut aussi être utilisé si cette connexion est activée.

Le connecteur doit renvoyer tous les identifiants actuels à conserver dans FoxIDs. Les valeurs absentes ou vides sont traitées comme des identifiants supprimés ; les anciennes valeurs ne restent pas des alias de connexion. Seuls les types activés sur la méthode de connexion peuvent être utilisés.

Conflits de comptes

Chaque utilisateur d’annuaire doit avoir un ID stable et unique, et ses identifiants ne doivent pas appartenir à un autre compte FoxIDs. FoxIDs recherche d’abord l’identifiant saisi dans l’annuaire, puis utilise l’ID renvoyé pour trouver ou créer le compte local. Si l’enregistrement des identifiants provoque un conflit avec un autre compte, le parcours s’arrête. Un administrateur doit corriger la configuration de l’annuaire ou du compte FoxIDs ; les comptes ne sont ni fusionnés ni réattribués automatiquement.

Un utilisateur interne existant sans lien avec l’annuaire ne peut pas se connecter via Directory Connector. L’activation ne relie pas automatiquement un compte à un utilisateur d’annuaire au seul motif que l’e-mail, le téléphone ou le nom d’utilisateur correspond.

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

La création d’utilisateurs et 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.
  • La création d’utilisateur dans le parcours de connexion appelle l’endpoint create-user.
  • 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.

Les endpoints de mot de passe reçoivent le directoryUserId stable de l’utilisateur chargé. L’annuaire vérifie l’état actuel du compte et les informations d’authentification pendant l’opération. Authentification, modification et réinitialisation renvoient un succès ou une erreur. La création d’utilisateur renvoie l’ID d’annuaire du compte créé, utilisé par FoxIDs pour une synchronisation distincte.

Les opérations de mot de passe utilisent l’ID d’annuaire stocké sur l’utilisateur FoxIDs chargé. Le connecteur vérifie l’état du compte et les informations d’authentification ou l’autorisation de réinitialisation nécessaires, exécute l’action et renvoie un succès ou une erreur. Les identifiants, attributs et claims ne sont renvoyés que par la synchronisation.

Après modification ou réinitialisation réussie, FoxIDs enregistre l’heure actuelle du changement et supprime les obligations de modifier ou définir un mot de passe. Il conserve aussi une copie locale si cela est configuré. La séquence active poursuit alors la gestion habituelle des comptes, de la récupération et de la MFA dans FoxIDs.

Si une action échoue ou si FoxIDs ne peut pas enregistrer les changements de mot de passe connus, le parcours s’arrête. Un changement déjà accepté par l’annuaire n’est pas annulé et FoxIDs ne répète pas automatiquement l’action après un délai dépassé ou un échec de réponse. La prochaine synchronisation actualise le compte local.

Lorsque Enable password policy est activé, FoxIDs vérifie le mot de passe actuel dans l’annuaire avant d’appliquer ses contrôles au nouveau mot de passe. Cela peut nécessiter un appel d’authentification supplémentaire avant change-password.

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.

Définition et récupération du mot de passe

Dès la première connexion, un utilisateur d’annuaire peut définir un mot de passe avec un code de confirmation reçu par e-mail ou SMS, parce qu’il a oublié son mot de passe ou doit en choisir un nouveau.

Pour Forgot your password?, saisissez un identifiant d’annuaire actuel d’un type activé sur la méthode de connexion. FoxIDs synchronise et crée le compte avant d’envoyer le code. La récupération par e-mail ou SMS doit être activée et l’utilisateur doit avoir accès au contact de récupération actuel renvoyé par l’annuaire.

Après vérification du code et envoi du nouveau mot de passe, FoxIDs appelle set-password avec l’ID d’annuaire stable. Renvoyez setPasswordEmail ou setPasswordSms et l’identifiant de contact associé pour imposer ce parcours de définition du mot de passe. FoxIDs utilise son parcours habituel.

Les codes de confirmation sont liés au compte pour lequel ils ont été émis. Les comptes gérés par un connecteur d’annuaire utilisent la même vérification de code que les autres utilisateurs internes. FoxIDs conserve la gestion habituelle des échecs de récupération sans exposer les diagnostics du connecteur.

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 possède une URL de base et cinq endpoints :

  • synchronise-user recherche un utilisateur et renvoie l’état actuel de son compte, ses identifiants et ses claims.
  • authentication valide le mot de passe actuel d’un utilisateur.
  • create-user crée un utilisateur dans l’annuaire externe et renvoie son ID d’annuaire permanent.
  • 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/synchronise-user
  • 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.

FoxIDs envoie la langue sélectionnée dans l’en-tête Accept-Language, par exemple Accept-Language: da-DK. Dans un parcours de connexion, il suit la langue choisie par ui_locales ou le navigateur, avec l’anglais comme langue de repli FoxIDs. L’API peut utiliser cet en-tête pour localiser les messages utilisateur et doit choisir son propre repli si la langue demandée n’est pas prise en charge. L’en-tête est envoyé aux cinq endpoints.

Requête de synchronisation

L’endpoint synchronise-user reçoit un identifiant utilisateur ou un ID d’annuaire connu. La première recherche lors d’une connexion ou récupération utilise l’identifiant saisi. FoxIDs utilise le directoryUserId enregistré pour les contrôles de sessions existantes et les requêtes avec refresh token, et l’ID renvoyé après create-user.

Une première recherche par e-mail :

{
  "email": "user1@somewhere.org"
}

Une vérification ultérieure du compte :

{
  "directoryUserId": "a1b2c3d4"
}

Utilisez directoryUserId comme clé de recherche faisant autorité lorsqu’il est présent. Sinon, recherchez exactement l’un des champs email, phone ou username. Renvoyez HTTP 200 avec l’ensemble des données utilisateur, y compris pour les comptes désactivés. Renvoyez le code user_deleted si l’ID connu est absent et user_not_exists si une recherche par identifiant seul ne trouve aucun compte. Un identifiant fourni ne prouve jamais la propriété du compte.

FoxIDs choisit l’identifiant de la requête selon les identifiants de connexion activés. Si seul le nom d’utilisateur est activé, une saisie au format e-mail est envoyée comme username. Les espaces périphériques sont supprimés. La saisie doit correspondre à un identifiant actuel de type activé dans la réponse ; le champ supposé de la requête ne limite pas les champs de réponse pouvant correspondre.

Pour les erreurs, voir Réponse d’erreur.

Réponse en cas de succès

L’endpoint synchronise-user renvoie HTTP 200 avec toutes les données utilisateur actuelles. Si la requête fournit un ID d’annuaire, la réponse doit contenir le même ID. FoxIDs le vérifie avant tout enregistrement. HTTP 204 ou des données incomplètes sont refusés.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "disableAccount": false,
  "changePassword": false,
  "setPasswordEmail": false,
  "setPasswordSms": false,
  "disableSetPasswordEmail": false,
  "disableSetPasswordSms": false,
  "passwordLastChanged": 1760000000,
  "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.
  • disableAccount contrôle la désactivation directe du compte. Le passage à l’état désactivé révoque les sessions FoxIDs et refresh-token grants de l’utilisateur.
  • changePassword impose un changement de mot de passe après vérification réussie des informations d’authentification.
  • setPasswordEmail et setPasswordSms imposent la définition d’un mot de passe via le parcours de code de confirmation correspondant. L’identifiant de contact doit être présent et la méthode de récupération activée.
  • disableSetPasswordEmail et disableSetPasswordSms désactivent les méthodes de récupération correspondantes.
  • passwordLastChanged est un horodatage Unix facultatif, non négatif, en secondes. Fourni par synchronisation, il actualise l’âge du mot de passe utilisé par FoxIDs. S’il est omis, l’horodatage existant est conservé. Une modification ou réinitialisation réussie enregistre l’heure actuelle dans FoxIDs ; une synchronisation ultérieure peut fournir l’horodatage de référence de l’annuaire.
  • 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.

FoxIDs ignore les claims dont le champ type ou value est absent, vaut null, est vide ou ne contient que des caractères d'espacement. Lorsque la journalisation des traces de messages est activée, la trace de la réponse inclut les claims reçus avant leur filtrage. Les longs messages de trace sont tronqués.

Les claims protégés, comme sid et auth_time, sont également retirés des réponses de synchronisation.

Requête d’authentification

L’endpoint authentication reçoit l’ID d’annuaire stable obligatoire et le mot de passe actuel.

{
  "directoryUserId": "a1b2c3d4",
  "password": "testpass1"
}

Vérifiez l’état actuel du compte dans l’annuaire et le mot de passe avant de renvoyer un succès. Vérifiez le mot de passe avant de fournir des indications de politique propres au compte.

Pour les erreurs, voir Réponse d’erreur.

Réponse en cas de succès

En cas de succès, renvoyez HTTP 204 sans corps de réponse.

Requête de création d’utilisateur

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

Champs :

  • Exactement un de email, phone ou username est envoyé.
  • 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 et requireMultiFactor sont les paramètres demandés pour la création de l’utilisateur dans FoxIDs.
  • claims contient les revendications autres que les identifiants, recueillies pendant la création de l’utilisateur dans FoxIDs.

Pour les erreurs, voir Réponse d’erreur.

Réponse en cas de succès

En cas de succès, renvoyez HTTP 200 avec l’ID d’annuaire permanent du compte créé :

{
  "directoryUserId": "a1b2c3d4"
}

FoxIDs appelle ensuite synchronise-user avec cet ID pour récupérer le compte complet et créer l’utilisateur interne FoxIDs.

Requête de changement de mot de passe

L’endpoint change-password reçoit l’ID d’annuaire obligatoire, le mot de passe actuel et le nouveau. Vérifiez le mot de passe actuel avant de fournir des indications de politique propres au compte.

{
  "directoryUserId": "a1b2c3d4",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Pour les erreurs, voir Réponse d’erreur.

Réponse en cas de succès

En cas de succès, renvoyez HTTP 204 sans corps de réponse. Le changement doit satisfaire l’exigence de mot de passe dans l’annuaire.

Requête de définition du mot de passe

L’endpoint set-password reçoit l’ID d’annuaire obligatoire et le nouveau mot de passe. FoxIDs l’appelle après autorisation de la réinitialisation ou définition, y compris la vérification de code dans les parcours de récupération. Le connecteur doit revérifier l’état actuel du compte avant toute modification.

{
  "directoryUserId": "a1b2c3d4",
  "password": "newpass1"
}

Pour les erreurs, voir Réponse d’erreur.

Réponse en cas de succès

En cas de succès, renvoyez HTTP 204 sans corps de réponse. La réinitialisation ou définition doit satisfaire l’exigence de mot de passe dans l’annuaire.

Réponse d’erreur

Tous les endpoints utilisent le même format d’erreur JSON. Renvoyez un code pris en charge par l’endpoint dans error et les détails diagnostiques dans errorMessage. Exemple d’un mot de passe refusé par authentication :

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

Utilisez ces codes d’état HTTP :

  • 401 avec le code invalid_api_id_secret lorsque l’authentification HTTP Basic est refusée.
  • 400, 401 ou 403 pour les autres codes pris en charge dans le tableau des endpoints ci-dessous.
  • 500 pour une défaillance technique du connecteur.

Le champ errorMessage contient du texte de diagnostic destiné aux journaux de FoxIDs et n’est pas affiché à l’utilisateur final. Indiquez la cause de l’erreur, mais n’incluez jamais de mots de passe, de secrets d’API ni de clés privées.

Seul l’endpoint authentication peut renvoyer login_rejected, après vérification de l’identifiant et du mot de passe. Il peut inclure un uiErrorMessage facultatif, que FoxIDs affiche en texte brut dans le formulaire de connexion. L’API fournit ce message dans la langue choisie via Accept-Language :

{
  "error": "login_rejected",
  "errorMessage": "Credentials verified; login rejected by directory policy.",
  "uiErrorMessage": "You cannot log in here. Contact support."
}

Si uiErrorMessage est omis, null, vide ou constitué uniquement d’espaces, FoxIDs affiche le même message général localisé que pour invalid_password et operation_rejected. Pour les autres codes pris en charge, FoxIDs ignore uiErrorMessage et choisit le message utilisateur dans ses propres textes localisés. Le texte diagnostique errorMessage n’est jamais utilisé comme message utilisateur de secours. Voir Erreurs d’authentification et confidentialité pour les exigences de vérification.

Les erreurs de authentication, change-password et set-password ne renvoient pas de données utilisateur, ne modifient pas le compte interne et ne révoquent pas les sessions ou refresh tokens existants. La synchronisation applique les modifications de compte de l’annuaire. Les tentatives d’authentification et de changement refusées comptent toujours dans la limite existante d’échecs de connexion.

Codes d’erreur pris en charge par endpoint :

Code d’erreur synchronise-user authentication create-user change-password set-password Signification
invalid_api_id_secret Oui Oui Oui Oui Oui Le nom d’utilisateur ou le secret de l’API pour HTTP Basic authentication est invalide.
user_exists Non Non Oui Non Non Un utilisateur avec l’identifiant fourni existe déjà dans l’annuaire externe.
user_not_exists Sans ID d’annuaire Non Non Non Non Aucun utilisateur d’annuaire ne correspond à la recherche par identifiant seul.
invalid_password Non Oui Non Non Non L’annuaire a refusé le mot de passe d’une requête d’authentification.
login_rejected Non Oui Non Non Non La connexion a été refusée après vérification de l’identifiant utilisateur et du mot de passe. Un uiErrorMessage facultatif s’affiche dans le formulaire de connexion.
invalid_current_password Non Non Non Oui Non L’annuaire a refusé le mot de passe actuel d’une requête de changement de mot de passe.
create_user_not_supported Non Non Oui Non Non Le connecteur ne prend pas en charge la création d’utilisateurs dans l’annuaire externe.
operation_rejected Non Oui Non Oui Oui L’opération ne peut pas aboutir, par exemple parce que le compte est indisponible. FoxIDs journalise errorMessage, ignore uiErrorMessage et affiche une erreur générale localisée sans modifier l’état du compte.
user_deleted Avec ID d’annuaire Non Non Non Non Un ID d’annuaire connu n’existe plus. FoxIDs révoque l’accès et supprime l’utilisateur pendant la synchronisation.
password_not_accepted Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini a été refusé par une règle de mot de passe de l’annuaire qui ne correspond pas à un code plus précis.
password_min_length Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini est plus court que la longueur minimale des mots de passe de l’annuaire.
password_max_length Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini est plus long que la longueur maximale des mots de passe de l’annuaire.
password_banned_characters Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini contient un ou plusieurs caractères ou mots refusés par l’annuaire.
password_complexity Non Oui Oui Oui Oui Ancienne erreur de complexité des caractères interprétée par FoxIDs comme password_character_variation. Utilisez l’un des deux codes d’erreur de caractères spécifiques pour les nouvelles intégrations.
password_character_repeat Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini contient trop de répétitions de caractères.
password_character_variation Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini ne contient pas une variété suffisante de caractères.
password_email_text_complexity Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini contient l’adresse e-mail de l’utilisateur ou une partie de celle-ci.
password_phone_text_complexity Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini contient le numéro de téléphone de l’utilisateur ou une partie de celui-ci.
password_username_text_complexity Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini contient le nom d’utilisateur ou une partie de celui-ci.
password_url_text_complexity Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini contient du texte lié à l’URL de FoxIDs.
password_risk Non Oui Oui Oui Oui Le mot de passe validé, utilisé pour créer un utilisateur, modifié ou défini est connu pour être risqué, compromis ou non sécurisé pour une autre raison.
password_history Non Non Non Oui Oui Le nouveau mot de passe a été refusé car il a déjà été utilisé.
password_expired Non Oui Non Non Non Le mot de passe fourni a été vérifié mais a expiré ; l’utilisateur doit le modifier avant de poursuivre l’authentification.
new_password_equals_current Non Non Non Oui Non Le nouveau mot de passe est identique au mot de passe actuel. set-password ne peut pas renvoyer cette erreur, car il ne reçoit pas le mot de passe actuel.

Lorsque FoxIDs doit contrôler sa politique avant un changement, il appelle d’abord authentication pour vérifier le mot de passe actuel. Si le connecteur renvoie password_expired depuis cette authentification, le changement peut continuer. L’endpoint change-password doit accepter un mot de passe actuel expiré mais vérifié et ne renvoyer que les erreurs prises en charge pour cette opération.

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.

Renvoyez uniquement un code pris en charge par l’endpoint et le directoryUserId fourni, comme indiqué ci-dessus. Un code non pris en charge, une réponse mal formée ou un état HTTP inattendu constitue une erreur d’intégration et conduit à la page d’erreur générale. Voir Dépannage des erreurs du navigateur pour retrouver les diagnostics grâce aux identifiants de la page d’erreur.

Erreurs d’authentification et confidentialité des utilisateurs

Un appelant non authentifié ne doit pas pouvoir déterminer si un nom d’utilisateur ou une adresse e-mail existe à partir d’un échec de connexion. Lors de l’authentification par mot de passe, FoxIDs traite les erreurs prises en charge comme suit :

Erreur du connecteur Résultat pour l’utilisateur
invalid_password, operation_rejected ou un compte jugé indisponible pendant la synchronisation Le même message de connexion générique, par exemple Courriel ou mot de passe erroné., traduit dans la langue active et adapté aux identifiants de connexion activés.
login_rejected Le uiErrorMessage fourni, ou le même message de connexion générique s’il est absent ou vide, au même endroit dans le formulaire de connexion.
password_not_accepted La page de changement de mot de passe avec des indications générales sur la politique de mot de passe.
password_expired ou une autre erreur spécifique de politique de mot de passe La page de changement de mot de passe avec les indications localisées correspondant à la politique de mot de passe.

Le connecteur doit vérifier le mot de passe actuel fourni avant de renvoyer une erreur de politique de mot de passe depuis authentication. Sinon, une page ou un message différent peut permettre à un attaquant de découvrir des utilisateurs et de confirmer leurs identifiants en devinant des noms d’utilisateur ou des adresses e-mail. Pour change-password, vérifiez le mot de passe actuel avant de renvoyer des indications propres au compte concernant le nouveau mot de passe. Les contrôles généraux de format ne doivent pas révéler si un compte existe.

Si un utilisateur n’est pas autorisé à utiliser ce parcours de connexion, vérifiez d’abord l’identifiant et le mot de passe fournis. Ne refusez sur la base de cette restriction qu’après vérification réussie des deux, afin de ne pas révéler si un identifiant deviné appartient à un utilisateur réel. Renvoyez login_rejected depuis authentication, indiquez la raison diagnostique dans errorMessage et éventuellement des indications sûres dans uiErrorMessage. Si les informations ne peuvent pas être vérifiées, renvoyez l’échec d’authentification habituel sans révéler la restriction.

FoxIDs se fie au connecteur pour vérifier les informations d’authentification avant login_rejected ; une recherche de compte réussie ou la connaissance de directoryUserId ne suffit pas. Avant vérification, affichez les instructions ou boutons d’autres méthodes de connexion indépendamment de l’existence d’un compte correspondant à l’identifiant fourni.

Seul synchronise-user rapporte l’état du compte : renvoyez toutes les données avec disableAccount: true pour un compte désactivé, ou le code user_deleted lorsqu’un ID connu n’existe plus. Les endpoints de mot de passe renvoient operation_rejected si le compte est indisponible. Contrairement à login_rejected, cette erreur n’exige pas de mot de passe vérifié car elle ne fournit jamais d’indication propre au compte au navigateur.

Traitez les échecs de manière cohérente pour les identifiants connus et inconnus, y compris les temps de réponse observables et la protection contre les tentatives répétées. Un message générique ne suffit pas à empêcher la découverte d’utilisateurs si une redirection, un statut ou un temps de réponse différent révèle le résultat. Suivez les recommandations OWASP sur les erreurs d’authentification lors de l’implémentation du connecteur.

Exemple d’API

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

Implémentations et clients de test doivent respecter les contrats ci-dessus : HTTP 200 avec les données utilisateur complètes pour synchronise-user, HTTP 200 avec l’ID créé pour create-user, et HTTP 204 sans corps pour les opérations de mot de passe réussies.

Composant Active Directory

FoxIDs inclut un Directory Connector pour Active Directory déployable sur IIS. Le composant implémente l’API Directory Connector pour un domaine AD/LDAP et peut synchroniser les comptes, valider, modifier et définir les mots de passe, ainsi que renvoyer les attributs AD et appartenances imbriquées à des groupes AD configurés sous forme de claims.

Configurer

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

  1. Sélectionnez l'onglet Paramètres.
  2. Sélectionnez l'onglet Environnement.
  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