Import et Export d’Utilisateurs

Auris fournit un système asynchrone d’import/export en masse pour les opérations d’onboarding ou de migration à grande échelle. Tu peux télécharger un fichier CSV ou JSON, suivre la progression comme un job et télécharger un fichier d’export avec les données des utilisateurs actuels.

Tous les jobs sont traités de façon asynchrone — si tu importes des milliers d’utilisateurs, tu n’as pas besoin de maintenir la connexion ouverte.

Import d’Utilisateurs

Formats de Fichiers Supportés

CSV

La première ligne doit être une ligne d’en-tête. Les colonnes reconnues sont :

Colonne	Obligatoire	Description
`email`	✅	Adresse e-mail de l’utilisateur (doit être unique)
`username`	Non	Séparé de l’e-mail ; généré automatiquement si absent
`firstName`	Non
`lastName`	Non
`password`	Non	Texte en clair — haché immédiatement. Si absent, l’utilisateur est créé sans credential.
`roles`	Non	Séparés par pipe : `admin\|viewer`


email,username,firstName,lastName,password,roles
[email protected],alice,Alice,Martin,MotDePasse1!,admin|viewer
[email protected],bob,Robert,Dupont,,viewer

JSON

Un tableau d’objets avec la même structure de champs que le CSV :


[
  {
    "email": "[email protected]",
    "username": "alice",
    "firstName": "Alice",
    "lastName": "Martin",
    "password": "MotDePasse1!",
    "roles": ["admin", "viewer"]
  },
  {
    "email": "[email protected]",
    "firstName": "Robert",
    "lastName": "Dupont",
    "roles": ["viewer"]
  }
]

Les mots de passe sont transmis via HTTPS et hachés immédiatement côté serveur en utilisant l’algorithme de hachage de Keycloak. Ils ne sont jamais stockés en clair. N’inclus pas de mots de passe dans des fichiers susceptibles d’être stockés dans des systèmes de gestion documentaire non sécurisés.

Effectuer un Import

Télécharge le fichier

POST/api/users/importRequires: manage:users

Télécharge un fichier d’import CSV ou JSON. Retourne un job ID utilisé pour suivre la progression.

Envoie comme multipart/form-data avec le fichier dans le champ file :


curl -X POST https://api.votreapp.com/api/users/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected];type=text/csv"

Réponse :


{
  "jobId": "import_01jk9x...",
  "status": "PENDING",
  "totalRows": 250,
  "createdAt": "2025-11-15T09:00:00Z"
}

Surveille la progression du job

GET/api/users/import/[id]Requires: manage:users

Récupère le statut d’un job d’import spécifique.

GET/api/users/importRequires: manage:users

Liste tous les jobs d’import, avec statut et résumé des erreurs.

États du job :

État	Description
`PENDING`	Job en file d’attente, traitement pas encore démarré
`PROCESSING`	Import des lignes en cours
`COMPLETED`	Toutes les lignes importées avec succès
`PARTIAL`	Certaines lignes ont échoué (voir `errorCount`)
`FAILED`	Job terminé avec une erreur irrémédiable (ex. format de fichier invalide)

Révise les résultats

Une fois que le job atteint COMPLETED ou PARTIAL, la réponse de statut inclut le compteur d’erreurs et les détails par ligne :


{
  "jobId": "import_01jk9x...",
  "status": "PARTIAL",
  "totalRows": 250,
  "successCount": 247,
  "errorCount": 3,
  "errors": [
    { "row": 14, "email": "[email protected]", "reason": "E-mail déjà existant" },
    { "row": 37, "email": "email-invalide", "reason": "Format d'e-mail invalide" },
    { "row": 102, "email": "[email protected]", "reason": "Username 'bob' déjà utilisé" }
  ]
}

Comportement de l’Import

E-mails dupliqués : ignorés silencieusement ; l’utilisateur existant n’est pas modifié.
Mot de passe absent : l’utilisateur est créé en état disabled-credentials (peut se connecter uniquement via magic links ou SSO jusqu’à ce qu’il définisse un mot de passe).
Assignation de rôles : les rôles sont assignés après la création de l’utilisateur. Si un nom de rôle n’existe pas, cette ligne échoue.
Traitement transactionnel : les lignes sont traitées indépendamment — l’échec d’une ligne ne fait pas de rollback sur celles déjà importées avec succès.

Export des Utilisateurs

POST/api/users/exportRequires: manage:users

Démarre un job d’export. Retourne un job ID. Le fichier d’export est généré de façon asynchrone.

GET/api/users/exportRequires: manage:users

Liste tous les jobs d’export avec statut et date d’expiration.

GET/api/users/export/[id]/downloadRequires: manage:users

Télécharge le fichier d’export complété. Retourne un CSV avec tous les champs exportables. Disponible jusqu’à l’expiration du fichier.

Champs d’Export

Le fichier CSV d’export inclut les colonnes suivantes :

Champ	Description
`id`	UUID interne de l’utilisateur Auris
`email`	Adresse e-mail
`username`	Nom d’utilisateur (si défini)
`firstName`
`lastName`
`enabled`	`true` ou `false`
`roles`	Liste séparée par pipes des rôles assignés
`createdAt`	Timestamp ISO 8601
`lastLogin`	Timestamp ISO 8601, ou vide si l’utilisateur ne s’est jamais connecté
`metadata`	Sérialisé comme chaîne JSON

Les hachages de mots de passe ne sont jamais inclus dans les exports, quelles que soient les autorisations. Si tu migres des utilisateurs vers un autre système d’authentification, tu devras forcer une réinitialisation de mot de passe ou utiliser une méthode d’authentification alternative.

Les fichiers d’export expirent après 7 jours. Vérifie le champ expiresAt dans la réponse du job. Après expiration, le fichier est automatiquement supprimé — tu devras démarrer un nouvel export.

Import/Export depuis la Console

Tu peux gérer les imports et exports directement depuis la Console Admin sans utiliser l’API.

Pour importer :

Va dans Utilisateurs → Importer des Utilisateurs.
Fais glisser un fichier CSV ou JSON dans la zone d’upload (ou clique pour naviguer).
Une fenêtre de prévisualisation affiche les 10 premières lignes analysées — vérifie que les colonnes sont correctement mappées.
Clique “Démarrer l’Import”. Une barre de progression apparaît qui se met à jour en temps réel.
Après la complétion, un résumé affiche les lignes réussies/échouées avec les détails des erreurs.

Pour exporter :

Va dans Utilisateurs → Exporter des Utilisateurs.
Clique “Générer l’Export”. Le job est mis en file d’attente.
Une fois complété, le bouton “Télécharger CSV” apparaît. Le fichier reste disponible pendant 7 jours.

Permissions Requises

Toutes les opérations d’import et export nécessitent la permission manage:users.

Pages Associées

Gestion des Utilisateurs — Opérations CRUD utilisateur unique via API
Provisioning SCIM 2.0 — Provisioning automatique continu via IdP
Console : Import/Export Utilisateurs — Guide complet de la Console