Passer au contenu principal
Vous pouvez effectuer une importation groupée d’utilisateurs dans Auth0 à l’aide du point de terminaison Create Import Users Job. Les importations groupées d’utilisateurs sont utiles pour migrer des utilisateurs depuis une base de données ou un service existant vers Auth0.
Si vous essayez d’utiliser plus d’une méthode de migration (par exemple, une migration automatique suivie d’une importation groupée d’utilisateurs), vous risquez d’obtenir une erreur DUPLICATED_USER. Cette erreur indique que l’utilisateur existe dans le répertoire interne des utilisateurs d’Auth0, mais pas dans votre locataire. Pour corriger cette erreur, supprimez l’utilisateur à l’aide du point de terminaison Delete a Connection User de l’Auth0 Management API, puis réessayez l’importation.

​
Prérequis

Avant de lancer la tâche d’importation des utilisateurs :
  • Configurez une connexion de base de données pour y importer les utilisateurs et activez-la pour au moins une application.
  • Si vous importez des mots de passe, assurez-vous qu’ils sont hachés à l’aide de l’un des algorithmes pris en charge. Les utilisateurs dont les mots de passe sont hachés avec des algorithmes non pris en charge devront réinitialiser leur mot de passe à leur première connexion après l’importation en bloc.
  • Si vous importez des inscriptions à la , assurez-vous qu’il s’agit d’un type pris en charge : email, phone ou totp.
  • Obtenez un jeton Management API pour les requêtes au point de terminaison de la tâche.
Si vous utilisez un fichier d’exportation provenant d’un locataire Auth0, vous devez convertir le fichier exporté de ndjson en JSON. Pour conserver les mêmes identifiants utilisateur, vous devez supprimer le préfixe auth0| de tous les identifiants utilisateur importés.Le processus d’importation ajoute automatiquement le préfixe auth0| aux identifiants utilisateur importés. Si vous ne supprimez pas le préfixe auth0| avant l’importation, les identifiants utilisateur seront renvoyés sous la forme auth0|auth0|...

​
Créer le fichier JSON des utilisateurs

Créez un fichier JSON contenant les données utilisateur que vous souhaitez importer dans Auth0. La manière d’exporter ces données vers un fichier JSON varie selon votre base de données d’utilisateurs actuelle. Le point de terminaison s’attend à recevoir le fichier JSON par sections. Ainsi, au lieu d’utiliser fs.readFileSync, vous devez utiliser fs.createReadStream. Le point de terminaison attend un flux de lecture transmis par pipeline plutôt que le fichier JSON complet. Pour en savoir plus sur le schéma du fichier JSON et voir des exemples, consultez Schéma de base de données pour l’importation en masse et exemples.
La taille maximale d’un fichier pour une importation en masse est de 500 KB. Vous devrez lancer plusieurs importations si vos données dépassent cette limite.

​
Demander l’importation groupée d’utilisateurs

Pour démarrer une tâche d’importation groupée d’utilisateurs, effectuez une requête POST vers le point de terminaison Create Import Users Job. Assurez-vous de remplacer les valeurs d’espace réservé MGMT_API_ACCESS_TOKEN, USERS_IMPORT_FILE.json, CONNECTION_ID et EXTERNAL_ID par votre de la Management API, votre fichier JSON d’utilisateurs, l’ID de connexion de la base de données et l’ID externe, respectivement.
ParamètreDescription
usersFichier au format JSON contenant les utilisateurs à importer.
connection_idID de la connexion dans laquelle les utilisateurs seront insérés. Vous pouvez récupérer cet ID à l’aide du point de terminaison GET /api/v2/connections.
upsertValeur booléenne : false par défaut. Lorsqu’elle est définie à false, les utilisateurs existants qui correspondent à une adresse courriel, à un ID d’utilisateur, à un téléphone ou à un nom d’utilisateur échoueront. Lorsqu’elle est définie à true, les utilisateurs existants qui correspondent à une adresse courriel seront mis à jour, mais uniquement avec des attributs pouvant être mis à jour par upsert. Pour obtenir la liste des champs du profil utilisateur pouvant faire l’objet d’un upsert lors de l’importation, consultez User Profile Structure: User profile attributes. Remarque : fournir une entrée utilisateur en double dans le fichier d’importation entraînera une erreur. Dans ce cas, Auth0 n’effectuera pas d’insertion suivie d’une mise à jour.
external_idChaîne facultative définie par l’utilisateur qui peut servir à faire le lien entre plusieurs tâches. Elle est renvoyée dans la réponse d’état de la tâche.
send_completion_emailValeur booléenne : true par défaut. Lorsqu’elle est définie à true, un courriel de fin de traitement est envoyé à tous les propriétaires du locataire une fois la tâche d’importation terminée. Si vous ne voulez pas que des courriels soient envoyés, vous devez définir explicitement ce paramètre à false.
Si la demande réussit, vous recevrez une réponse semblable à la suivante : 
{
  "status": "pending",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "upsert": false,
  "external_id": "EXTERNAL_ID",
  "send_completion_email": true
}
L’entité renvoyée représente la tâche d’importation. Lorsque la tâche d’importation d’utilisateurs se termine et que send_completion_email a été défini à true, le ou les administrateurs du locataire recevront un courriel les informant si la tâche a échoué ou réussi. Dans le cas d’une tâche ayant échoué, le courriel peut aviser le ou les administrateurs qu’une erreur est survenue lors de l’analyse du fichier JSON des utilisateurs pendant l’importation.

​
Tâches d’importation concurrentes

Le point de terminaison Create Import Users Job est limité à deux tâches d’importation concurrentes. Si vous demandez des tâches supplémentaires alors que deux sont déjà en attente, une réponse 429 Too Many Requests est renvoyée : 
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "There are 2 active import users jobs, please wait until some of them are finished and try again
}

​
Vérifier l’état de la tâche

Pour vérifier l’état d’une tâche, envoyez une requête GET au point de terminaison Get a Job. Assurez-vous de remplacer les valeurs d’espace réservé MGMT_API_ACCESS_TOKEN et JOB_ID par votre jeton d’accès de la Management API et l’id de la tâche d’importation des utilisateurs. Selon l’état de la tâche d’importation des utilisateurs, vous recevrez une réponse semblable à l’une des suivantes : En attente 
{
  "status": "pending",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID"
}
Terminé Si une tâche est terminée, la réponse sur l’état de la tâche inclura le nombre total d’enregistrements traités avec succès, ayant échoué, insérés et mis à jour. 
{
  "status": "completed",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID",
  "summary": {
    "failed": 0,
    "updated": 0,
    "inserted": 1,
    "total": 1
  }
}
Échec S’il y a une erreur dans la tâche, son état sera renvoyé comme ayant échoué. Notez toutefois que des renseignements utilisateur non valides, comme un courriel invalide, n’entraîneront pas l’échec de l’ensemble de la tâche. 
{
  "status": "failed",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID",
}
Pour obtenir plus de détails sur les entrées en échec, consultez Récupérer les entrées en échec ci-dessous.

​
Délais d’expiration des tâches

Toutes les tâches d’importation d’utilisateurs expirent après deux (2) heures. Si votre tâche ne se termine pas dans ce délai, elle est marquée en échec. De plus, toutes les données liées à votre tâche sont automatiquement supprimées après 24 heures et ne sont plus accessibles ensuite. Par conséquent, nous vous recommandons fortement d’enregistrer les résultats de la tâche au moyen du mécanisme de stockage de votre choix.

​
Récupérer les entrées en échec

Toutes les données liées à la tâche sont automatiquement supprimées après 24 heures et ne sont plus accessibles ensuite. C’est pourquoi nous vous recommandons fortement d’enregistrer les résultats de la tâche à l’aide du mécanisme de stockage de votre choix.
S’il y a eu des erreurs lors de la tâche d’importation d’utilisateurs, vous pouvez en obtenir les détails en envoyant une requête GET au point de terminaison Obtenir les détails des erreurs de tâche. Assurez-vous de remplacer les valeurs d’espace réservé MGMT_API_ACCESS_TOKEN et JOB_ID par votre jeton d’accès à la Management API et l’ID de votre tâche d’importation d’utilisateurs. Si la requête aboutit, vous recevrez une réponse semblable à la suivante. Les champs sensibles, comme hash.value, seront masqués dans la réponse. 
[
    {
        "user": {
            "email": "test@test.io",
            "user_id": "7af4c65cb0ac6e162f081822422a9dde",
            "custom_password_hash": {
                "algorithm": "ldap",
                "hash": {
                    "value": "*****"
                }
            }
        },
        "errors": [
            {
                "code": "...",
                "message": "...",
                "path": "..."
            }
        ]
    }
]
Chaque objet d’erreur inclut un code d’erreur et un message qui fournit plus de détails sur l’erreur. Les codes d’erreur possibles sont :
  • ANY_OF_MISSING
  • ARRAY_LENGTH_LONG
  • ARRAY_LENGTH_SHORT
  • CONFLICT
  • CONFLICT_EMAIL
  • CONFLICT_USERNAME
  • CONNECTION_NOT_FOUND
  • DUPLICATED_USER
  • ENUM_MISMATCH
  • FORMAT
  • INVALID_TYPE
  • MAX_LENGTH
  • MAXIMUM
  • MFA_FACTORS_FAILED
  • MIN_LENGTH
  • MINIMUM
  • NOT_PASSED
  • OBJECT_REQUIRED
  • PATTERN

​
Bonnes pratiques pour les migrations à grande échelle

Lorsque vous importez un grand nombre d’utilisateurs (ce qui nécessite 10 tâches ou plus), suivez ces recommandations pour assurer le succès de la migration :

​
Taille des fichiers et fractionnement

Répartissez les enregistrements d’utilisateurs en petits blocs de moins de 400 KB par fichier. Cela permet de traiter environ 1 000 utilisateurs par tâche avec moins de 10 champs de métadonnées par utilisateur, tout en restant largement sous la limite de taille de fichier de 500 KB.

​
Planification des tâches et concurrence

Comme Auth0 limite les importations d’utilisateurs à deux tâches simultanées par locataire, utilisez un framework de planification des tâches (comme Bull ou Agenda) pour :
  • Planifier systématiquement les tâches d’importation
  • Appliquer la limite de concurrence requise
  • Suivre la progression de l’importation afin de reprendre là où vous vous êtes arrêté en cas d’interruption
  • Conserver l’historique des tâches et leur état actuel

​
Stratégie de gestion des erreurs

  • N’interrompez pas le processus d’importation lorsqu’un seul utilisateur échoue. Importez tous les utilisateurs, puis traitez les problèmes par la suite.
  • Implémentez une tâche de « finalisation » qui passe en revue toutes les tâches générées et regroupe les enregistrements ayant échoué dans un nouveau fichier.
  • Corrigez les erreurs dans les enregistrements regroupés ayant échoué, puis importez-les dans une nouvelle tâche.
  • Prévoyez une stratégie de reprise pour gérer les pertes de connexion réseau et les défaillances temporaires.

​
Considérations relatives au mode upsert

Faites preuve de prudence lorsque vous activez le mode upsert :
  • Les importations en mode upsert sont plus lentes que les importations standard.
  • Le mode upsert ne prend pas en charge la fusion de user_metadata ou app_metadata. Les métadonnées existantes seront entièrement remplacées par les nouvelles valeurs.
  • Utilisez le mode upsert uniquement si vous devez mettre à jour des utilisateurs existants et si vous comprenez bien ces limites.

​
Conservation des données

N’oubliez pas que toutes les données liées aux tâches sont automatiquement supprimées après 24 heures. Conservez les résultats des tâches et les détails des erreurs au moyen de votre propre mécanisme de stockage afin d’en assurer le suivi et l’analyse à long terme.

​
En savoir plus