Control API - utilisateurs et applications d'authentification

Utilisez la FoxIDs Control API pour provisionner des utilisateurs internes et gérer les applications d'authentification enregistrées par chaque utilisateur. Ce guide se concentre sur les opérations permettant de synchroniser les enregistrements entre des deployments FoxIDs.

Avant d'appeler ces opérations, configurez l'authentification et les droits d'accès Control API. Swagger reste la référence exacte pour toutes les propriétés utilisateur, les filtres, les règles de validation et les schémas de response :

• Swagger (OpenAPI) JSON
• Swagger UI

Base des endpoints

Les exemples utilisent FoxIDs Cloud :

https://control.foxids.com/api/{tenant_name}/{track_name}

Remplacez {tenant_name} par le nom du tenant et {track_name} par le nom technique de l'environnement. Modifiez le host pour un deployment self-hosted. Envoyez l'access token Control API dans le header Authorization: Bearer {access_token}.

Les opérations sur les utilisateurs et les applications d'authentification exigent un droit utilisateur sur l'environnement cible. N'accordez que l'opération read, create, update ou delete nécessaire via la hiérarchie des droits Control API.

Identifiants utilisateur

Chaque utilisateur interne doit avoir au moins un identifiant de connexion : adresse e-mail, numéro de téléphone ou nom d'utilisateur. Les adresses e-mail peuvent compter jusqu'à 100 caractères et les noms d'utilisateur jusqu'à 60 caractères. Les adresses e-mail et les noms d'utilisateur sont normalisés en minuscules, et les espaces environnants sont supprimés de tous les identifiants.

Les opérations individuelles identifient l'utilisateur avec le query parameter email, phone ou username. La response contient aussi un userId généré par le serveur. Cet ID est unique et persistant, même si un identifiant de connexion change, et doit servir à associer des applications d'authentification ou d'autres ressources.

Pour les utilisateurs de Directory Connector, conservez le lien stable directoryUserId lors des mises à jour du compte. La synchronisation à la demande remplace les identifiants, paramètres et claims gérés par l’annuaire ; modifiez-les dans l’annuaire faisant autorité. Les applications d’authentification enregistrées et les attributions d’accès FoxIDs sont conservées.

Opérations utilisateur

Les opérations individuelles sont regroupées sous tenant users dans Swagger.

Les claims personnalisés peuvent inclure un valueType facultatif : String, Boolean, Number, JsonObject ou JsonArray. Toutes les entrées de values restent des chaînes et partagent le type sélectionné. Omettez valueType pour String. L’API rejette les valeurs qui ne correspondent pas au type sélectionné ; conservez ce type lors de la lecture et de la mise à jour des claims. Les mêmes choix s’appliquent aux claims des nœuds de structures d’accès et aux claims du premier administrateur lors de la création d’un tenant. Consultez les types des valeurs de claims pour les limites numériques et le comportement JWT/SAML.

Utilisez au besoin phone={phone} ou username={username} au lieu de email={email}. Ajoutez chaque endpoint à la base des endpoints.

Lister et filtrer les utilisateurs

GET /!users accepte filterEmail, filterPhone, filterUsername, filterUserId et filterClaimValue. Chaque filtre effectue une recherche partielle insensible à la casse. Avec plusieurs filtres, l'utilisateur est renvoyé si l'un d'eux correspond.

La response contient une collection data et un paginationToken opaque. Pour la page suivante, répétez le même request avec la valeur retournée dans paginationToken. Continuez jusqu'à ce qu'aucun token ne soit renvoyé. Ne l'interprétez pas et ne le modifiez pas.

La response utilisateur indique si un mot de passe est configuré et sa dernière date de modification, mais ne renvoie jamais le mot de passe ni son hash actuel.

Créer un utilisateur

Le create-request prend en charge l'état du compte, les identifiants vérifiés, les claims personnalisés, la politique de mot de passe, la configuration par e-mail ou SMS et les paramètres MFA par utilisateur. Cet exemple crée un utilisateur sans mot de passe et exige sa configuration par e-mail :

POST https://control.foxids.com/api/{tenant_name}/{track_name}/!user
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "email": "alice@example.com",
  "emailVerified": true,
  "setPasswordEmail": true,
  "claims": [
    {
      "claim": "role",
      "values": ["employee"]
    }
  ]
}

Un create-request peut contenir un mot de passe en clair, des champs de hash pris en charge ou aucune donnée de mot de passe. N'envoyez jamais les deux formats. Les mots de passe en clair sont vérifiés selon la politique choisie ; les hashes importés ne le sont pas. Sans données, utilisez setPasswordEmail ou setPasswordSms si l'utilisateur doit créer son mot de passe à la connexion.

Créer un utilisateur existant renvoie 409 Conflict, et la limite d'utilisateurs du plan du tenant s'applique. Une opération utilisateur simultanée peut verrouiller temporairement la création ; réessayez un 423 Locked après un court délai.

Mettre à jour un utilisateur

PUT /!user est une mise à jour complète, pas un patch. Lisez l'utilisateur actuel, conservez les propriétés inchangées, appliquez les modifications et envoyez toute la représentation modifiable. La collection de claims et les flags de compte/MFA sont remplacés par les valeurs du request. Les mots de passe et enregistrements d'applications ont leurs propres opérations.

Identifiez l'utilisateur avec email, phone ou username. Pour modifier un identifiant, conservez sa valeur actuelle dans le champ et définissez updateEmail, updatePhone ou updateUsername. Une chaîne vide supprime l'identifiant ; une propriété omise le laisse inchangé. Conservez au moins un identifiant de connexion.

Le passage de disableAccount de false à true révoque les refresh token grants et sessions actives. Réactiver le compte autorise de nouvelles connexions sans restaurer les sessions révoquées.

Les revendications personnalisées des utilisateurs ne peuvent pas utiliser de noms de revendications protégés, tels que sid et auth_time.

Gérer les mots de passe

Utilisez PUT /!usersetpassword pour une définition administrative ou une migration :

• Fournissez password pour appliquer la politique et mettre à jour l'historique.
• Fournissez passwordHashAlgorithm et passwordHash, ainsi que passwordHashSalt lorsque l’algorithme l’exige, pour importer un hachage précalculé pris en charge sans validation de la politique.
• Omettez les deux formats pour supprimer le mot de passe actuel.

Les mêmes formats de hachage sont acceptés lors de la création d’un utilisateur ou du provisionnement en masse :

Par exemple, cette requête administrative de mot de passe importe un hachage bcrypt synthétique :

{
  "email": "alice@example.com",
  "passwordHashAlgorithm": "bcrypt",
  "passwordHash": "$2b$10$..CA.uOD/eaGAOmJB.yMBu3YunYvFEoaS5IJZ/wiqfQ/EWx.HaqjC"
}

N’incluez pas password avec les champs de hachage. Un hachage ou un sel sans son algorithme est rejeté. Les chaînes bcrypt mal formées, les variantes non prises en charge, les coûts hors limites et les sels bcrypt séparés sont rejetés avant la persistance. Consultez le hachage des mots de passe pour les paramètres et la limite bcrypt de 72 octets.

La valeur facultative passwordLastChanged correspond au temps Unix en secondes. Utilisez changePassword pour obliger l’utilisateur à choisir un nouveau mot de passe à la prochaine connexion concernée. L’import d’un hachage ignore les contrôles de politique pendant l’import ; la politique choisie s’applique toujours à la connexion. La connexion préserve le hachage importé et la date de modification. La définition ou la modification d’un mot de passe en clair utilise le format PBKDF2 par défaut.

Utilisez PUT /!userchangepassword quand le mot de passe actuel est connu. L'opération le vérifie et valide le nouveau selon la politique et l'historique.

Le point de terminaison de l’historique des mots de passe est destiné aux scénarios contrôlés de migration et de récupération. Il accepte aussi les entrées bcrypt avec les mêmes limites de format et de coût, sans sel séparé. Sa réponse détaillée contient des hachages de mots de passe et PUT remplace tout l’historique. Appliquez les mêmes protections que pour les hachages importés et ne journalisez pas les corps des requêtes ou des réponses.

Provisionnement en masse

PUT /!users accepte de 1 à 1 000 utilisateurs par request. Au maximum 100 entrées peuvent contenir un mot de passe en clair, car chacun doit être hashé de façon sûre. Les requests sans mot de passe en clair, y compris avec des hashes précalculés pris en charge, peuvent contenir 1 000 utilisateurs.

L’import en masse crée de nouveaux utilisateurs ou remplace les utilisateurs correspondants ; il ne fusionne pas les propriétés individuelles et ne peut pas modifier les identifiants e-mail, téléphone ou nom d’utilisateur. Traitez-le comme un import de remplacement. Utilisez la mise à jour individuelle pour les modifications courantes du cycle de vie du compte lorsque l’état existant et l’identifiant utilisateur persistant doivent être conservés.

DELETE /!users accepte de 1 à 1 000 e-mails, téléphones ou noms d'utilisateur dans userIdentifiers. Consultez Importer de nombreux utilisateurs pour les formats, les performances et le seed tool.

Supprimer les utilisateurs et révoquer l'accès

La suppression individuelle ou en masse révoque les refresh token grants et sessions actives avant de supprimer le compte. Elle est permanente. Utilisez les opérations de suppression d'applications d'authentification pour ne supprimer que leurs enregistrements.

Les requests de création, mise à jour, mot de passe et suppression figurent dans l'audit Control. Les lectures ne sont pas écrites comme audit-events.

Blocages après échec de connexion

Utilisez les opérations de liste et de détail pour examiner les blocages, puis supprimez un blocage lorsqu’un administrateur autorise sa levée.

Les blocages par utilisateur possèdent un userIdentifier. Utilisez cette valeur et le type d’échec pour récupérer ou lever un blocage utilisateur. Le filtre de liste filterUserIdentifier compare les identifiants sans tenir compte de la casse.

Les blocages DirectorySynchronisation possèdent un sequenceId et omettent userIdentifier. Utilisez le sequenceId exact, sensible à la casse, et le type d’échec pour récupérer ou lever un blocage de synchronisation, sans paramètre userIdentifier. filterSequenceId permet de trouver les blocages de la séquence. Fournir filterUserIdentifier et filterSequenceId recherche les blocages correspondant à l’un ou l’autre ; le filtre de type d’échec reste applicable à tous les résultats. La limite de recherches est partagée par tous les identifiants saisis dans la même séquence.

Enregistrements d'applications d'authentification

Les opérations des applications d'authentification sont regroupées sous tenant user authenticator apps dans Swagger. Une opération de liste renvoie des résumés sûrs, tandis que l'opération de détail renvoie les données sensibles nécessaires à une synchronisation contrôlée.

Ajoutez chaque endpoint à la base des endpoints. Exemple :

GET https://control.foxids.com/api/{tenant_name}/{track_name}/!userauthenticatorapps?userId=e061ed17-7b44-48a8-b224-ecdb800ed5cc
Authorization: Bearer {access_token}

Ressource d'enregistrement

La création et la mise à jour utilisent la ressource d'enregistrement complète :

{
  "userId": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "createTime": 1785769200,
  "secret": "TOTP-SHARED-SECRET",
  "recoveryCode": {
    "hashAlgorithm": "P2HS512:10",
    "hash": "RECOVERY-CODE-HASH",
    "hashSalt": "RECOVERY-CODE-SALT"
  }
}

Les propriétés se comportent comme suit :

• userId est l'ID utilisateur FoxIDs stable.
• id est un ID d'enregistrement persistant fourni par le client lors de la création. Il sélectionne l'enregistrement lors de la mise à jour et ne peut pas être modifié.
• createTime est exprimé en secondes Unix. Il est facultatif lors de la création et prend par défaut l'heure actuelle. S'il est omis lors d'une mise à jour, la valeur existante est conservée.
• secret est le TOTP secret partagé, requis lors de la création et de la mise à jour.
• recoveryCode contient les données de hash du recovery code et est omis lorsqu'aucun recovery code n'est configuré.

Un utilisateur peut avoir au maximum cinq enregistrements d'applications d'authentification. Une création avec un ID existant renvoie 409 Conflict ; une création après avoir atteint la limite renvoie 400 Bad Request.

Synchroniser les enregistrements

Un service de synchronisation peut combiner l'Authenticator App notification API interactive avec ces opérations Control API :

1. Recevez la notification registered contenant user_id et registration_id.
2. Obtenez l'enregistrement depuis le source deployment avec l'opération de détail.
3. Créez l'enregistrement dans le target deployment ou mettez-le à jour si le même ID existe déjà.

Les opérations Control API de création, mise à jour et suppression n'appellent pas l'Authenticator App notification API. La synchronisation ne crée donc pas de boucle de notification.

Sécurité

Les opérations de détail, création et mise à jour exposent ou acceptent un secret d'application d'authentification et les données de hash du recovery code. Accordez le droit utilisateur requis uniquement aux clients approuvés, utilisez TLS, protégez les payloads stockés et ne journalisez pas les request ou response bodies.

Utilisez l'opération de liste lorsque seuls les ID d'enregistrement et les dates de création sont nécessaires. Elle ne renvoie pas le secret ni les données de hash du recovery code.

Propriété de compatibilité

La propriété activeTwoFactorApp de l'API utilisateur générale est deprecated et sa suppression est prévue après le 1er août 2027. Dans une update-request, false supprime encore tous les enregistrements pour compatibilité ; true ou une valeur omise les laisse inchangés. Les nouvelles intégrations doivent utiliser les endpoints des applications d'authentification.

Réponses d'erreur

Les réponses d'erreur courantes des opérations utilisateur et d'application d'authentification sont :

• 400 Bad Request si les identifiants, données d'authentification, filtres ou données de ressource sont invalides, ou si la limite est atteinte.
• 401 Unauthorized si l'access token manque ou est invalide.
• 403 Forbidden si le client n'a pas le droit utilisateur requis sur l'environnement.
• 404 Not Found si l'utilisateur ou l'enregistrement d'application n'existe pas.
• 409 Conflict si l'utilisateur existe déjà ou si un ID d'enregistrement est réutilisé.
• 423 Locked si la création ou l'import en masse est temporairement verrouillé. Réessayez après un court délai.

Utilisez le response body pour les détails de validation. Consultez Swagger UI pour les réponses déclarées par opération.

Sessions impersonées

Les sessions actives conservent les identifiants de l’utilisateur authentifié d’origine. Les détails d’impersonation identifient séparément la cible, notamment son subject, le format du subject, l’e-mail, le téléphone, le nom d’utilisateur et la référence de compte interne lorsqu’ils sont disponibles. Vous pouvez rechercher une session active avec les identifiants de l’un ou l’autre utilisateur.

Les claims du jeton de rafraîchissement représentent l’identité émise à l’application ; les détails d’impersonation du grant identifient l’utilisateur authentifié d’origine et la cible sélectionnée. Les deux comptes associés participent à la révocation d’accès. Voir impersonation pour la configuration du flux et le comportement des sessions.

Documentation associée

• Authentification et droits d'accès Control API
• Présentation de FoxIDs Control
• Utilisateurs internes
• Authentification à deux facteurs et multi-facteur
• Importer de nombreux utilisateurs