Saltar al contenido principal
Puede importar datos de usuario en bloque en Auth0 mediante el endpoint Create Import Users Job. Las importaciones en bloque son útiles para migrar usuarios desde una base de datos o un servicio existentes a Auth0.
Si intenta usar más de un método de migración (por ejemplo, una migración automática y después una importación masiva de usuarios), puede encontrarse con el error DUPLICATED_USER. Este error indica que el usuario existe en el almacén de usuarios interno de Auth0, pero no en su inquilino. Para corregir este error, elimine el usuario con el endpoint Delete a Connection User de Auth0 Management API y, a continuación, vuelva a intentar la importación.

​
Requisitos previos

Antes de iniciar el trabajo de importación de usuarios:
  • Configure una conexión de base de datos en la que importar los usuarios y habilítela para al menos una aplicación.
  • Si va a importar contraseñas, asegúrese de que tengan hash con uno de los algoritmos compatibles. Los usuarios cuyas contraseñas tengan hash con algoritmos no compatibles deberán restablecer su contraseña cuando inicien sesión por primera vez después de la importación masiva.
  • Si va a importar inscripciones de , asegúrese de que sean de un tipo compatible: email, phone o totp.
  • Obtenga un token de la Management API para las solicitudes al endpoint de trabajos.
Si está usando un archivo de exportación de un inquilino de Auth0, debe convertir el archivo exportado de ndjson a JSON. Para conservar los mismos IDs de usuario, debe eliminar el prefijo auth0| de todos los IDs de usuario importados.El proceso de importación agrega automáticamente el prefijo auth0| a los IDs de usuario importados. Si no elimina el prefijo auth0| antes de importar, los IDs de usuario se devolverán como auth0|auth0|...

​
Crear un archivo JSON de usuarios

Cree un archivo JSON con los datos de usuario que desea importar en Auth0. La forma de exportar los datos de usuario a un archivo JSON variará según la base de datos de usuarios que ya tenga. El endpoint de espera partes del archivo JSON. Por lo tanto, en lugar de usar fs.readFileSync, requiere fs.createReadStream. El endpoint espera un flujo de lectura canalizado en lugar del archivo JSON completo. Para obtener más información sobre el esquema del archivo JSON y ver ejemplos, lea Esquema de la base de datos y ejemplos de importación masiva.
El límite de tamaño de archivo para una importación masiva es de 500 KB. Deberá iniciar varias importaciones si sus datos superan este tamaño.

​
Solicitar una importación masiva de usuarios

Para iniciar un trabajo de importación masiva de usuarios, envía una solicitud POST al endpoint Create Import Users Job. Asegúrate de reemplazar los valores de marcador de posición MGMT_API_ACCESS_TOKEN, USERS_IMPORT_FILE.json, CONNECTION_ID y EXTERNAL_ID por tu de la Management API, el archivo JSON de usuarios, el ID de la conexión de la base de datos y el ID externo, respectivamente.
ParámetroDescripción
usersArchivo en formato JSON que contiene los usuarios que se importarán.
connection_idID de la conexión en la que se insertarán los usuarios. Puede recuperar el ID mediante el endpoint GET /api/v2/connections.
upsertValor booleano; false de forma predeterminada. Cuando se establece en false, se producirá un error con los usuarios existentes que coincidan por dirección de correo electrónico, ID de usuario, teléfono o username. Cuando se establece en true, los usuarios existentes que coincidan por dirección de correo electrónico se actualizarán, pero solo con atributos que admitan upsert. Para obtener una lista de los campos del perfil de usuario que se pueden actualizar mediante upsert durante la importación, consulte User Profile Structure: User profile attributes. Nota: Incluir una entrada de usuario duplicada en el archivo de importación provocará un error. En este caso, Auth0 no realizará una inserción seguida de una actualización.
external_idCadena opcional definida por el usuario que puede utilizarse para correlacionar varios trabajos. Se devuelve como parte de la respuesta de estado del trabajo.
send_completion_emailValor booleano; true de forma predeterminada. Cuando se establece en true, se envía un correo electrónico de finalización a todos los propietarios del inquilino cuando finaliza el trabajo de importación. Si no desea que se envíen correos electrónicos, debe establecer explícitamente este parámetro en false.
Si la solicitud se realiza correctamente, recibirá una respuesta similar a la siguiente: 
{
  "status": "pending",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "upsert": false,
  "external_id": "EXTERNAL_ID",
  "send_completion_email": true
}
La entidad devuelta representa el trabajo de importación. Cuando finalice el trabajo de importación de usuarios, si send_completion_email se estableció en true, los administradores del inquilino recibirán un correo electrónico para notificarles si el trabajo falló o se completó correctamente. Un correo electrónico sobre un trabajo fallido podría notificar a los administradores que no se pudo procesar el archivo JSON de usuarios durante la importación.

​
Trabajos de importación simultáneos

El endpoint Create Import Users Job tiene un límite de dos trabajos de importación simultáneos. Si se solicitan trabajos adicionales cuando ya hay dos pendientes, se devuelve una respuesta 429 Too Many Requests: 
{
  "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
}

​
Consultar el estado del trabajo

Para consultar el estado de un trabajo, realiza una solicitud GET al endpoint Get a Job. Asegúrate de reemplazar los valores de marcador de posición MGMT_API_ACCESS_TOKEN y JOB_ID por tu token de acceso de la Management API y el id del trabajo de importación de usuarios. Según el estado del trabajo de importación de usuarios, recibirás una respuesta similar a una de las siguientes: Pendiente 
{
  "status": "pending",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID"
}
Completado Si un trabajo se ha completado, la respuesta de estado del trabajo incluirá los totales de registros procesados correctamente, fallidos, insertados y actualizados. 
{
  "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
  }
}
Fallido Si hay un error en el trabajo, se devolverá como fallido. Sin embargo, tenga en cuenta que la información de usuario no válida, como un correo electrónico no válido, no hará que falle todo el trabajo. 
{
  "status": "failed",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID",
}
Para conocer los detalles de los registros fallidos, consulte Retrieve failed entries más abajo.

​
Tiempos de espera de los trabajos

Todos los trabajos de importación de usuarios vencen después de dos (2) horas. Si su trabajo no se completa dentro de este plazo, se marca como fallido. Además, todos los datos relacionados con su trabajo se eliminan automáticamente después de 24 horas y ya no se podrá acceder a ellos. Por lo tanto, recomendamos encarecidamente que almacene los resultados del trabajo mediante el mecanismo de almacenamiento que prefiera.

​
Recuperar entradas fallidas

Todos los datos relacionados con el trabajo se eliminan automáticamente después de 24 horas y ya no se puede acceder a ellos. Por este motivo, le recomendamos encarecidamente que almacene los resultados del trabajo con el mecanismo de almacenamiento que prefiera.
Si hubo errores en el trabajo de importación de usuarios, puede obtener los detalles del error haciendo una solicitud GET al endpoint Get Job Error Details. Asegúrese de reemplazar los valores de marcador de posición MGMT_API_ACCESS_TOKEN y JOB_ID por su token de acceso de la Management API y el ID del trabajo de importación de usuarios. Si la solicitud se realiza correctamente, recibirá una respuesta similar a la siguiente. Los campos sensibles, como hash.value, se ocultarán en la respuesta. 
[
    {
        "user": {
            "email": "test@test.io",
            "user_id": "7af4c65cb0ac6e162f081822422a9dde",
            "custom_password_hash": {
                "algorithm": "ldap",
                "hash": {
                    "value": "*****"
                }
            }
        },
        "errors": [
            {
                "code": "...",
                "message": "...",
                "path": "..."
            }
        ]
    }
]
Cada objeto de error incluirá un código de error y un mensaje que lo explica con más detalle. Los posibles códigos de error son:
  • 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

​
Prácticas recomendadas para migraciones a gran escala

Al importar un gran volumen de usuarios (lo que requiere 10 o más trabajos), siga estas recomendaciones para garantizar una migración exitosa:

​
Tamaño de archivo y fragmentación

Divida los registros de usuario en fragmentos pequeños de menos de 400 KB por archivo. Esto permite procesar aproximadamente 1.000 usuarios por trabajo con menos de 10 campos de metadatos por usuario, sin superar con holgura el límite de tamaño de archivo de 500 KB.

​
Programación y concurrencia de trabajos

Dado que Auth0 limita las importaciones de usuarios a dos trabajos simultáneos por inquilino, use un framework de programación de trabajos (como Bull o Agenda) para:
  • Programar los trabajos de importación de forma sistemática
  • Aplicar el límite de simultaneidad requerido
  • Hacer un seguimiento del progreso de la importación para reanudarla donde se interrumpió
  • Mantener el historial de trabajos y sus estados actuales

​
Estrategia de gestión de errores

  • No interrumpa el proceso de importación por errores de un solo usuario. Importe todos los usuarios y resuelva los problemas después.
  • Implemente un trabajo de “finalización” que revise todos los trabajos generados y recopile los registros fallidos en un archivo nuevo.
  • Corrija cualquier error en los registros fallidos recopilados e impórtelos como un trabajo nuevo.
  • Incluya una estrategia de reintento para gestionar caídas de la conexión de red y errores temporales.

​
Consideraciones sobre el modo upsert

Ten cuidado al habilitar el modo upsert:
  • Las importaciones con upsert son más lentas que las importaciones estándar.
  • El modo upsert no admite la combinación de user_metadata ni app_metadata. Los metadatos existentes se sobrescribirán por completo con los nuevos valores.
  • Usa el modo upsert solo cuando necesites actualizar usuarios existentes y entiendas estas limitaciones.

​
Retención de datos

Recuerde que todos los datos relacionados con los trabajos se eliminan automáticamente transcurridas 24 horas. Guarde los resultados de los trabajos y los detalles de los errores en su propio mecanismo de almacenamiento para su seguimiento y análisis a largo plazo.

​
Más información