Exportation en lot d’utilisateurs

Découvrez comment exporter des listes d’utilisateurs et leurs métadonnées.

Vous pouvez utiliser le point de terminaison POST /api/v2/jobs/users-exports pour créer une tâche qui exporte tous les utilisateurs associés à une connexion, ou tous les utilisateurs du locataire.

Pour obtenir la liste des champs de profil utilisateur qui peuvent être exportés, consultez Structure du profil utilisateur.

Lorsque vous créez votre tâche, vous devez fournir :

• ID de la connexion à partir de laquelle vous souhaitez exporter des utilisateurs (facultatif)
• Le format du fichier d’exportation (CSV ou compatible avec JSON)
• Le nombre maximal d’enregistrements d’utilisateurs à exporter (facultatif; si omis, tous les enregistrements seront exportés)
• Les champs liés à l’utilisateur (comme l’ID utilisateur ou le nom) que vous souhaitez inclure dans l’exportation

Vous aurez également besoin d’un jeton d’accès valide à la Management API.

​

Créer un corps de requête

Au besoin, repérez le connection_id et le domaine de votre locataire Auth0 dans l’Auth0 Dashboard. Créez un nouveau fichier texte avec le corps de requête ci-dessous :

{
   "connection_id":"connection_id",
   "format":"csv",
   "limit":20,
   "fields":[
      {
         "name":"user_id"
      },
      {
         "name":"email"
      },
      {
         "name":"user_metadata.country"
      }
   ]
}

Remplacez connection_id par l’ID de votre connexion à la base de données, ou supprimez-le pour exporter tous les utilisateurs du locataire.

​

Exemple de requête

Scopes requis : read:users

La réponse devrait ressembler à ceci :

{
  "type": "users_export",
  "status": "pending",
  "connection_id": "con_0000000000000001",
  "format": "csv",
  "limit": 5,
  "fields": [
    {
      "name": "user_id"
    },
    {
      "name": "name"
    },
    {
      "name": "email"
    },
    {
      "name": "identities[0].connection",
      "export_as": "provider"
    }
  ],
  "connection": "Username-Password-Authentication",
  "created_at": "2017-11-02T23:34:03.803Z",
  "id": "job_coRQCC3MHztpuTlo"
}

​

Inclure les métadonnées de l’utilisateur dans le CSV exporté

Si vous exportez des données utilisateur au format CSV et que vous souhaitez inclure des métadonnées, précisez chaque champ de métadonnées à exporter. Vous pouvez exporter jusqu’à 30 champs.

Vous ne pouvez pas exporter l’intégralité de app_metadata ou de user_metadata en CSV. Vous devez préciser explicitement les champs des objets de métadonnées.

Pour exporter app_metadata ou user_metadata sous forme d’objets uniques, utilisez le format compatible avec JSON et incluez le champ voulu dans le paramètre fields du corps de la requête. Par exemple :

{"name":"app_metadata"}

Comme vous ne pouvez exporter qu’un maximum de 30 champs, il est recommandé d’utiliser le format JSON si les données utilisateur comportent de nombreux champs.

Par exemple, pour des métadonnées structurées comme ceci :

{
  "consent": {
      "given": true,
      "date": "01/23/2019",
      "text_details": "{yourURL}"
  }
}

La requête d’exportation (pour les trois champs) se présenterait comme suit :

Dans les fichiers CSV d’exportation des utilisateurs, nous appliquons un échappement aux données de type chaîne conformément aux normes OWASP visant à atténuer les injections CSV :

• Les guillemets doubles sont précédés d’un guillemet double.
• Chaque chaîne est précédée d’une apostrophe.
• Chaque chaîne est entourée de guillemets doubles.

Cela ne s’applique pas aux dates générées par Auth0 au format ISO 8601.

​

Format compatible avec JSON

Si vous exportez les données dans un format compatible avec JSON, vous n’avez qu’à fournir la propriété racine ; il n’est pas nécessaire de nommer chaque propriété interne individuellement, puisqu’elles seront incluses automatiquement.

En raison de la taille importante des fichiers d’exportation, les fichiers exportés par Auth0 utilisent le format NDJSON, tandis que la fonctionnalité d’importation attend un fichier JSON.

Avant de pouvoir importer des utilisateurs à partir d’une exportation générée par Auth0, vous devrez convertir le fichier de NDJSON en JSON à l’aide de la bibliothèque de votre choix (par exemple jq).

Dans ce cas, pour le même exemple que précédemment, la requête ressemblerait à ceci :

​

Vérifier l’état de l’exportation

Une fois que vous avez créé la tâche pour exporter vos utilisateurs, vous pouvez en vérifier l’état à l’aide du point de terminaison Get a Job.

Indiquez l’ID de la tâche (reçu dans la réponse lors de la création de la tâche). Si vous utilisez l’exemple de requête ci-dessous, remplacez l’espace réservé {yourJobId} par la valeur de l’ID.

Scopes requis : create:users, read:users, create:passwords_checking_job

Vous devriez obtenir une réponse semblable à celle-ci :

{
  "type": "users_export",
  "status": "completed",
  "connection_id": "con_lCvO...a",
  "format": "csv",
  "limit": 5,
  "fields": [
    {
      "name": "user_id"
    },
    {
      "name": "name"
    },
    {
      "name": "email"
    },
    {
      "name": "identities[0].connection",
      "export_as": "provider"
    }
  ],
  "location": "pus3-auth0-export-users-us-east-2.s3.us-east-2.amazonaws.com/job_coRQCC3MHztpuTlo/auth0docs2.csv.gz?Expires=1509725589&Key-Pair-Id=APKAJPL62IJALBDMSSCA&Signature=l2JaFXP~BATnfagb64PK-qbX9QaZREDYNW0q5QeHuV-MaDpZjpABDXfHHLh2SsCMQz~UO-QsCSfI81l0lvCKzZPZL6cZHK7f~ixlZOK~MHKJuvMqsUZMbNluNAwhFmgb2fZ86yrB1c-l2--H3lMELAk7hKUwwSrNBlsfbMgQ-i41nMNnsYdy3AVlNVQkwZyx~w-IEHfJDHsqyjia-jfDbIOLQvr8~D9PwZ-xOzROxDwgxrt3undtz80bkgP5hRKOAbHC7Y-iKWa2bzNZYHqzowTrlh7Ta60cblJR46NfF9cNqn9jqRGVv-lsvUD9FxnImCCk~DL6npJnzNLjHvn4-CaWq6KdQnwWgCnZ3LZkxXDVWLLIQQaoc6i~xbuGnnbtKRePFSnpqbt2mAUYasdxTOWuUVK8wHhtfZmRYtCpwZcElXFO9Qs~PTroYZEiS~UHH5byMLt2x4ChkHnTG7pIhLAHN~bCOLk8BN2lOkDBUASEVtuJ-1i6cKCDqI2Ro9YaKZcCYzeQvKwziX6cgnMchmaZW77~RMOGloi2EffYE31OJHKiSVRK7RGTykaYN5S2Sg7W0ZOlLPKBtCGRvGb8rJ6n3oPUiOC3lSp7v0~dkx1rm-jO8mKWZwVtC0~4DVaXsn8KXNbj0LB4mjKaDHwXs16uH1-aCfFnMK7sZC2VyCU_",
  "connection": "Username-Password-Authentication",
  "created_at": "2017-11-02T23:34:03.803Z",
  "id": "job_coRQCC3MHztpuTlo"
}

​

Trouver les données d’exportation

Vous pouvez accéder à vos fichiers d’exportation à l’aide de l’URL fournie comme valeur du paramètre location. Le nom de votre locataire correspond aussi au nom de votre fichier. Par exemple, si le nom de votre locataire est auth0docs, votre fichier sera auth0docs.csv ou auth0docs.json. Lorsque vous accédez à l’URL, le téléchargement du fichier démarre automatiquement.

Le lien de téléchargement est valide pendant 60 secondes. Une fois ce délai écoulé, vous avez 24 heures pour utiliser de nouveau l’URL avant l’expiration de la tâche.

​

Nettoyage des tâches

Toutes les données liées à vos tâches 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.

​

Exemple de filtrage

Il se peut que vous souhaitiez filtrer le fichier .csv exporté pour n’en conserver qu’un sous-ensemble précis de données, par exemple la date de la dernière connexion des utilisateurs à votre application.

1. Effectuez un appel POST au point de terminaison Create export user’s job du Management API pour exporter les utilisateurs dans un fichier .csv :

   1. Créez une nouvelle tâche :

      curl -L 'https://{account.namespace}/api/v2/jobs/users-exports' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer MGMT_API_TOKEN' \
      -d '{"format":"csv"}'
      

   2. Vérifiez l’état :

      curl -L 'https://{account.namespace}/api/v2/jobs/JOB_ID' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer MGMT_API_TOKEN'
      

2. Accédez au fichier dans le dossier Téléchargements de votre machine locale.

3. Utilisez un outil en ligne de commande pour ajouter un filtre. Dans cet exemple, nous utilisons Miller :

   mlr --csv filter '$last_login >= "2024-01-01T00:00:00Z"' file.csv > filtered.csv