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 et noms d'utilisateur sont normalisés en minuscules, et les espaces de début et de fin sont supprimés.

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.

Opérations utilisateur

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

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.

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, passwordHash et passwordHashSalt pour importer un hash pris en charge sans validation de politique.
• Omettez les deux formats pour supprimer le mot de passe actuel.

passwordLastChanged est une date Unix facultative en secondes. changePassword oblige l'utilisateur à choisir un nouveau mot de passe lors de la prochaine connexion applicable.

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.

L'endpoint d'historique est destiné aux migrations et récupérations contrôlées. Sa response détaillée contient du matériel de hash et PUT remplace tout l'historique. Protégez-le comme les hashes importés et ne journalisez pas les request/response bodies.

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 ou remplace les utilisateurs correspondants ; il ne fusionne pas les propriétés et ne peut pas renommer les identifiants e-mail, téléphone ou nom d'utilisateur. Traitez-le comme un import de remplacement. Utilisez la mise à jour individuelle pour conserver l'état et le userId persistant.

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.

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.

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