Importación y Exportación de Usuarios

Auris proporciona un sistema de importación y exportación masiva de datos de usuario. La importación es útil para migrar desde un proveedor de identidad existente, incorporar un lote de empleados desde un sistema de RRHH o inicializar usuarios en un nuevo tenant. La exportación es útil para crear copias de seguridad, auditar tu base de usuarios o migrar a otro sistema.

Ambas operaciones son asíncronas. Auris procesa el archivo en segundo plano y expone un endpoint de estado del trabajo para que puedas sondear la finalización o mostrar un indicador de progreso.

Formatos de Importación

Auris acepta dos formatos de archivo para la importación de usuarios.

Formato CSV

La primera fila debe ser una fila de encabezado. El orden de las columnas no importa, pero los nombres de las columnas deben coincidir exactamente.

email,username,firstName,lastName,password,roles
[email protected],alice,Alice,Rossi,ContraseñaTemporal123!,member
[email protected],bob,Bob,Marley,,member|billing-admin
[email protected],,Carol,White,,,

Referencia de columnas:

Formato JSON

El archivo debe contener un array JSON de objetos de usuario. Los campos coinciden con los nombres de las columnas del CSV.

[
  {
    "email": "[email protected]",
    "username": "alice",
    "firstName": "Alice",
    "lastName": "Rossi",
    "password": "ContraseñaTemporal123!",
    "roles": ["member"]
  },
  {
    "email": "[email protected]",
    "roles": ["member", "billing-admin"]
  }
]

Proceso de Importación

curl -X POST https://auth.tuapp.com/api/users/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant: tu-tenant" \
  -F "[email protected]"

{
  "ok": true,
  "data": {
    "id": "import_01HX...",
    "fileName": "usuarios.csv",
    "format": "CSV",
    "status": "PENDING",
    "totalRows": 0,
    "processedRows": 0,
    "successCount": 0,
    "errorCount": 0,
    "createdAt": "2025-06-10T14:00:00Z"
  }
}

{
  "ok": true,
  "data": {
    "id": "import_01HX...",
    "status": "PARTIAL",
    "totalRows": 150,
    "processedRows": 150,
    "successCount": 147,
    "errorCount": 3,
    "errors": [
      {
        "row": 12,
        "email": "[email protected]",
        "reason": "La dirección de email ya existe en este tenant"
      },
      {
        "row": 67,
        "reason": "Falta campo requerido: email"
      },
      {
        "row": 103,
        "email": "email-incorrecto",
        "reason": "Formato de dirección de email no válido"
      }
    ]
  }
}

Comportamiento de la Importación

Comprensión de cómo Auris maneja los casos extremos durante la importación:

Emails duplicados: Si ya existe un usuario con el mismo email en el tenant, la fila se omite y se cuenta como error. El registro del usuario existente no se modifica.

Contraseñas ausentes: Los usuarios creados sin contraseña se aprovisionan en un estado de credenciales deshabilitadas. Deben usar el flujo “Olvidé mi Contraseña” o recibir un email de restablecimiento de contraseña activado por un administrador para obtener acceso.

Asignación de roles: Los roles listados en el archivo de importación se asignan después de la creación del usuario. Si el nombre de un rol no existe en el tenant, la fila se marca como error parcial — el usuario se crea, pero la asignación de rol falla.

Sincronización con Keycloak: Cada usuario importado correctamente se crea tanto en la base de datos de Auris como en el realm subyacente de Keycloak. Los dos registros están vinculados por keycloakId.

Modelo de transacciones: Auris procesa las filas individualmente en lugar de en una sola transacción. Un fallo en la fila 50 no revierte las filas 1–49.

Listado de Trabajos de Importación

Exportación de Usuarios

La exportación de usuarios genera un archivo que contiene todos los usuarios activos (no eliminados) del tenant. La operación es asíncrona: activas la exportación y luego descargas el archivo cuando la generación está completa.

Activar una exportación

{
  "format": "JSON"
}

Respuesta:

{
  "ok": true,
  "data": {
    "id": "export_01HX...",
    "format": "JSON",
    "status": "PENDING",
    "totalUsers": 0,
    "expiresAt": "2025-06-17T14:00:00Z",
    "createdAt": "2025-06-10T14:00:00Z"
  }
}

Sondear la finalización

Descargar el archivo

curl https://auth.tuapp.com/api/users/export/export_01HX.../download \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant: tu-tenant" \
  -o exportacion-usuarios.json

Campos exportados

La exportación incluye:

Guía en la Consola

La interfaz de importación/exportación de la Consola está disponible en Configuración → Importar/Exportar.

Importación:

1. Arrastra y suelta un archivo .csv o .json en la zona de carga, o haz clic para abrir el selector de archivos.
2. La Consola muestra una vista previa de las primeras 10 filas para validación antes de enviarlas.
3. Tras el envío, una barra de progreso rastrea el procesamiento. La barra se actualiza cada pocos segundos mediante sondeo.
4. Cuando el trabajo finaliza, un resumen de resultados muestra el recuento de éxitos, el recuento de errores y un enlace al cuadro de detalles de errores.

Exportación:

1. Selecciona el formato de exportación (CSV o JSON).
2. Haz clic en “Exportar Usuarios”. La Consola muestra el estado del trabajo.
3. Cuando la exportación está completa, aparece un botón “Descargar”. Haz clic para guardar el archivo.
4. Las exportaciones anteriores se listan con su estado, fecha de creación y fecha de caducidad.

Permisos Requeridos

Páginas Relacionadas

• Gestión de Usuarios — CRUD individual de usuarios a través de la API y la Consola
• Aprovisionamiento SCIM 2.0 — Sincronización automatizada y continua desde un IdP externo
• Consola: Importar/Exportar — Guía completa de la Consola con capturas de pantalla