Exportación masiva de usuarios

Aprende a exportar listas de usuarios y sus metadatos.

Puedes usar el endpoint POST /api/v2/jobs/users-exports para crear un trabajo que exporte todos los usuarios asociados a una conexión o todos los usuarios del tenant.

Para ver una lista de los campos del perfil de usuario que se pueden exportar, consulta User Profile Structure.

Cuando crees el trabajo, deberás proporcionar:

• El ID de la conexión desde la que quieres exportar usuarios (opcional)
• El formato del archivo de exportación (CSV o compatible con JSON)
• El número máximo de registros de usuario que se exportarán (opcional; si se omite, se exportarán todos los registros)
• Los campos relacionados con el usuario (como el ID o el nombre) que quieres incluir en la exportación

También necesitarás un Management API Access Token válido.

​

Crear el cuerpo de la solicitud

Si lo deseas, puedes encontrar el connection_id y el nombre de dominio de tu tenant de Auth0 en el Auth0 Dashboard. Crea un nuevo archivo de texto con el cuerpo de la solicitud que aparece a continuación:

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

Actualiza el connection_id con el ID de conexión de tu base de datos o elimínalo para exportar todos los usuarios del tenant.

​

Ejemplo de solicitud

Scopes requeridos: read:users

La respuesta debería ser algo así:

{
  "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"
}

​

Incluir metadatos de usuario en el CSV exportado

Si exportas datos de usuario en formato CSV y quieres incluir información de metadatos, especifica cada campo de metadatos que quieras exportar. Puedes exportar hasta 30 campos.

No puedes exportar todo el contenido de app_metadata o user_metadata en CSV. Debes especificar explícitamente los campos de los objetos de metadatos.

Para exportar app_metadata o user_metadata como objetos individuales, usa el formato compatible con JSON e incluye el campo que quieras en el parámetro fields del cuerpo de la solicitud. Por ejemplo:

{"name":"app_metadata"}

Como solo puedes exportar hasta 30 campos, se recomienda usar el formato JSON si los datos del usuario tienen muchos campos.

Por ejemplo, para metadatos con una estructura como esta:

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

La solicitud de exportación (para los tres campos) sería así:

En los archivos CSV de exportación de usuarios, aplicamos escape a los datos de tipo cadena conforme a los estándares de OWASP para mitigar la inyección de CSV:

• A los caracteres de comillas dobles se les antepone otro carácter de comillas dobles.
• Cada cadena va precedida de un carácter de comilla simple.
• Cada cadena se encierra entre comillas dobles.

Esto no se aplica a las fechas generadas por Auth0 en formato ISO 8601.

​

Formato compatible con JSON

Si exportas los datos en un formato compatible con JSON, solo necesitas indicar la propiedad raíz; no hace falta nombrar cada propiedad interna por separado, ya que se incluirán automáticamente.

Los archivos de exportación de Auth0 utilizan el formato NDJSON debido a su gran tamaño, mientras que la funcionalidad de importación espera un archivo JSON.

Antes de poder importar usuarios mediante una exportación generada por Auth0, tendrás que convertir el archivo de NDJSON a JSON con la biblioteca que prefieras (como jq).

En este caso, para el mismo ejemplo que usamos antes, la solicitud tendría este aspecto:

​

Comprobar el estado de la exportación

Una vez que hayas creado el trabajo para exportar tus usuarios, puedes consultar su estado mediante el endpoint Get a Job.

Proporciona el ID del trabajo (que recibiste en la respuesta al crearlo). Si estás usando la solicitud de ejemplo que aparece a continuación, sustituye el marcador de posición {yourJobId} por el valor del ID.

Scopes necesarios: create:users, read:users, create:passwords_checking_job

Deberías obtener una respuesta como la siguiente:

{
  "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"
}

​

Encontrar datos de exportación

Puede acceder a sus archivos de exportación mediante la URL proporcionada como valor del parámetro location. El nombre de su tenant también es el nombre de su archivo. Por ejemplo, si el nombre de su tenant es auth0docs, su archivo será auth0docs.csv o auth0docs.json. Cuando acceda a la URL, la descarga del archivo comenzará automáticamente.

El enlace de descarga es válido durante 60 segundos. Si este período vence, tendrá 24 horas para volver a usarlo antes de que expire el trabajo.

​

Limpieza de trabajos

Todos los datos relacionados con sus trabajos se eliminan automáticamente después de 24 horas y no se puede acceder a ellos después. Por lo tanto, recomendamos encarecidamente guardar los resultados del trabajo con el mecanismo de almacenamiento que prefiera.

​

Ejemplo de filtro

Puede que quieras filtrar el archivo .csv exportado para obtener un subconjunto concreto de tus datos, como la fecha del último inicio de sesión de los usuarios en tu aplicación.

1. Haz una llamada POST al endpoint Create export user’s job de la Management API para exportar usuarios a un archivo .csv:

   1. Crea un nuevo trabajo:

      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. Comprueba el estado:

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

2. Ve al archivo en la carpeta de descargas de tu equipo local.

3. Usa una herramienta de línea de comandos para añadir un filtro. En este ejemplo, usamos Miller:

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