Importation en bloc de données utilisateur dans les connexions à une base de données Auth0

Migrez des utilisateurs d’une base de données ou d’un service existant vers Auth0 à l’aide d’importations en bloc pour les connexions à une base de données.

Vous pouvez importer en bloc des données utilisateur existantes dans une connexion à une base de données Auth0. Cela peut être utile pour migrer des utilisateurs d’une base de données ou d’un service existant vers Auth0.

Pour importer en bloc des données utilisateur, créez d’abord un fichier de données utilisateur au format JSON attendu par Auth0, puis lancez une tâche pour importer ces données à l’aide du Dashboard ou de la Management API.

​

Prérequis

Auth0 Dashboard

• Vous devez disposer d’une connexion à une base de données dans laquelle importer les données utilisateur. Il peut s’agir de l’une des connexions suivantes :

  • Une connexion à une base de données utilisant le répertoire d’utilisateurs d’Auth0.
  • Une connexion à une base de données personnalisée utilisant votre répertoire d’utilisateurs externe, avec le mode d’importation activé.

• Vous devez disposer de l’un des rôles de membre du tenant suivants :

  • Admin
  • Editor - Users

Management API

• Vous devez disposer d’une connexion à une base de données dans laquelle importer les données utilisateur. Il peut s’agir de l’une des connexions suivantes :

  • Une connexion à une base de données utilisant le répertoire d’utilisateurs d’Auth0.
  • Une connexion à une base de données personnalisée utilisant votre répertoire d’utilisateurs externe, avec le mode d’importation activé.

• Vous devez disposer d’un jeton Management API ou en créer un pour effectuer des requêtes vers le endpoint des tâches, avec les scopes nécessaires pour le endpoint Create import users job.

​

1. Créer le fichier de données utilisateur

Commencez par mettre vos données utilisateur existantes au format JSON afin de les importer dans Auth0, en respectant la structure définie dans le schéma JSON des données utilisateur et la référence des propriétés.

Les points suivants peuvent vous être utiles lors de la création du fichier de données utilisateur :

• La taille maximale d’un fichier pour une importation en bloc est de 500 Ko. Si vos données dépassent cette limite, vous devez les répartir dans plusieurs fichiers plus petits à téléverser dans le cadre de plusieurs tâches.

  À titre indicatif, un fichier contenant environ 1 000 utilisateurs et moins de 10 champs de métadonnées par utilisateur respecte généralement cette limite de taille.

• Si vous partez d’une exportation de données utilisateur Auth0 :

  • Les importations en bloc prennent en charge le format JSON, mais les exportations d’utilisateurs générées par Auth0 sont au format NDJSON. Vous pouvez convertir le format NDJSON en JSON à l’aide d’outils comme jq.

  • Les importations en bloc ajoutent automatiquement le préfixe auth0| aux ID des utilisateurs importés, mais les exportations d’utilisateurs générées par Auth0 comportent déjà ce préfixe dans les ID utilisateur.

  Pour conserver les mêmes ID utilisateur, supprimez le préfixe auth0| de tous les ID utilisateur importés. Sinon, les ID utilisateur comporteront le préfixe deux fois (auth0|auth0|<user_id>).

• Vous pouvez importer des données utilisateur avec des mots de passe hachés à l’aide d’un algorithme pris en charge. Les utilisateurs dont les mots de passe sont hachés à l’aide d’algorithmes non pris en charge doivent réinitialiser leur mot de passe lorsqu’ils se connectent pour la première fois après l’importation en bloc.

  Si un utilisateur ne s’est pas connecté à l’aide du custom_password_hash importé initialement, vous pouvez le mettre à jour en soumettant de nouveau les données utilisateur avec une valeur différente pour custom_password_hash dans une nouvelle tâche avec les upserts activés.

​

2. Importez les données utilisateur dans votre connexion à une base de données

Auth0 Dashboard

Pour importer des données utilisateur à l’aide du Auth0 Dashboard :

1. Accédez à Dashboard > Gestion des utilisateurs > Utilisateurs.

2. Dans le coin supérieur droit de la page, sélectionnez Importer/exporter des utilisateurs pour accéder à la page Importer/exporter des utilisateurs.

3. Sélectionnez Importer des utilisateurs pour accéder à la page Importer des utilisateurs.

   

4. Sous Fichier JSON des utilisateurs, sélectionnez + Choisir un fichier et téléversez le fichier JSON des données utilisateur.

5. Sous Connexion, ouvrez le menu déroulant et sélectionnez la connexion de base de données dans laquelle vous souhaitez importer les données utilisateur.

6. Facultativement, cochez Mettre à jour les utilisateurs préexistants dans la connexion. Lorsqu’un utilisateur importé correspond à un utilisateur existant dans la connexion de base de données, vous pouvez choisir de mettre à jour les données ou non :

   • Par défaut, les mises à jour sont désactivées. Les importations d’utilisateurs correspondant à une adresse courriel, un ID utilisateur, un téléphone ou un username échouent.

   • Lorsque les mises à jour sont activées, les importations d’utilisateurs correspondant à une adresse courriel mettent à jour tous les attributs pouvant être mis à jour.

7. Facultativement, cochez Envoyer un courriel de fin d’opération à tous les propriétaires du tenant. Lorsque cette option est activée, un courriel de fin d’opération est envoyé à tous les administrateurs de tenant lorsque le job réussit ou échoue.

8. Pour soumettre le job, sélectionnez Importer des utilisateurs.

API de Management

Pour importer des données d’utilisateurs à l’aide de la Management API, appelez le point de terminaison Create Import Users Job (POST /jobs/users-imports). Consultez la documentation du point de terminaison pour connaître les détails des paramètres du corps de la requête et des schémas de réponse.

Pour utiliser les exemples ci-dessous :

• Remplacez les variables fictives MGMT_API_ACCESS_TOKEN, USERS_IMPORT_FILE.json, CONNECTION_ID et EXTERNAL_ID par vos propres valeurs.

  Vous pouvez consulter l’ID de la connexion à la base de données dans le Dashboard ou l’obtenir à l’aide du endpoint Get all connections de la Management API.

• Vous pouvez également définir upsert. Lorsqu’un utilisateur importé correspond à un utilisateur existant dans la connexion à la base de données, vous pouvez choisir de mettre à jour ou non les données :

  • Par défaut, les opérations d’upsert sont désactivées. Les importations d’utilisateurs dont l’adresse courriel, l’ID utilisateur, le numéro de téléphone ou le nom d’utilisateur correspondent échouent.

  • Lorsque upsert est activé, les importations d’utilisateurs dont l’adresse courriel correspond mettent à jour tous les attributs pouvant être mis à jour.

• Facultativement, définissez `send_completion_email afin d’envoyer un courriel de confirmation à tous les administrateurs de tenant lorsque le job réussit ou échoue.

Lorsque la création d’une tâche réussit, la valeur retournée contient des renseignements sur la tâche, dont son ID.

​

3. Vérifier le statut d’une tâche

Auth0 Dashboard

Pour vérifier le statut d’une tâche :

1. Accédez à Dashboard > User Management > Users.

2. Dans le coin supérieur droit de la page, sélectionnez Import/Export Users pour accéder à la page Import/Export Users. Une fois que vous avez lancé au moins une tâche, cette page répertorie les tâches que vous avez soumises.

3. Pour afficher plus de renseignements sur une tâche, sélectionnez More info à côté de celle-ci.

Les statuts des tâches comprennent Job creation failed, Job created, user import failed et Job created, user import succeeded.

Management API

Pour vérifier le statut d’une tâche, envoyez une requête au endpoint Get a job (GET /jobs) avec l’ID de la tâche. Consultez la documentation de l’endpoint pour en savoir plus sur ses paramètres et les schémas de réponse.

Le status de la tâche renvoyée peut être pending, completed ou failed. Si la tâche est terminée, l’objet summary de la réponse inclut le total des enregistrements réussis, échoués, insérés et mis à jour.

Si une tâche échoue, vous pouvez obtenir les détails de l’erreur en envoyant une requête au endpoint Get job error details (GET /jobs/{id}/errors) avec l’ID de la tâche. Chaque objet d’erreur de la réponse comprend un code d’erreur et un message expliquant l’erreur plus en détail. 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

Les tâches échouent en cas d’erreur, mais non lorsque les renseignements utilisateur sont non valides (par exemple, une adresse courriel non valide).

​

Limites

• Un maximum de deux tâches d’importation peut s’exécuter simultanément par tenant.

• Les tâches d’importation d’utilisateurs expirent après deux (2) heures. Si une tâche ne se termine pas dans ce délai, elle est marquée comme ayant échoué.

• Toutes les données associées aux tâches sont automatiquement supprimées après 24 heures.

• Les entrées d’utilisateurs en double dans le fichier d’importation entraînent une erreur. Elles ne donnent pas lieu à une importation suivie d’un upsert.

• Les upserts ne fusionnent ni user_metadata ni app_metadata. Les métadonnées existantes sont entièrement remplacées par les nouvelles métadonnées.

​

Bonnes pratiques pour les migrations à grande échelle

Lors de l’importation de grandes quantités de données utilisateur (nécessitant 10 tâches ou plus), nous recommandons les stratégies suivantes :

• Utilisez un framework de planification de tâches (comme Bull ou Agenda). Cela vous permet de :

  • Respecter la limite de concurrence requise.

  • Prévoir une stratégie de reprise pour gérer les interruptions de connexion réseau et les échecs temporaires.

  • Conserver les résultats des tâches et les détails des erreurs au-delà de la période de suppression.

• N’interrompez pas les importations en cas d’échec pour un seul utilisateur. Mettez plutôt en œuvre une tâche de « finalisation » qui examine toutes les tâches générées et regroupe les enregistrements en échec dans un nouveau fichier. Corrigez les erreurs dans ces enregistrements, puis importez-les dans une nouvelle tâche.

• Faites preuve de prudence lorsque vous activez le mode upsert. Les importations avec upsert sont plus lentes que les importations standard et ne fusionnent pas les métadonnées. Utilisez le mode upsert lorsque vous devez mettre à jour des utilisateurs existants et que vous comprenez ces limites.