Migración de usuarios

Logto admite tanto la migración masiva como la migración just-in-time de usuarios existentes desde otro sistema de identidad. Esta guía explica cómo importar usuarios en masa a través del Management API y qué considerar antes de migrar.

Elige una estrategia de migración

Estrategia	Elígela cuando	Cómo funciona
Migración masiva	Puedes exportar los registros de usuarios y los hashes de contraseñas en un formato compatible con Logto.	Importa los usuarios antes del cambio a través del Management API, siguiendo el resto de esta guía.
Migración just-in-time	Necesitas verificar contraseñas contra el sistema existente, no puedes exportar hashes de contraseñas compatibles o quieres migrar usuarios activos gradualmente.	Configura una Acción posterior a la verificación del primer factor. En el primer inicio de sesión con contraseña del usuario, Logto verifica las credenciales mediante tu Acción, crea o actualiza el usuario y almacena un nuevo hash de contraseña local.

La migración just-in-time mantiene el servicio de autenticación heredado en la ruta de la solicitud de inicio de sesión hasta que los usuarios sean migrados. Utiliza un endpoint HTTPS rápido y confiable y mantenlo disponible durante el periodo de migración.

Esquema de usuario

Antes de comenzar, echemos un vistazo al esquema de usuario en Logto. Hay 3 partes del esquema de usuario que debes conocer:

1. Datos básicos: es la información básica del perfil del usuario, puedes hacer coincidir los datos de tu perfil de usuario existente.
2. Datos personalizados: almacena información adicional del usuario, puedes usar esto para guardar archivos que no puedan coincidir con los datos básicos.
3. Identidades sociales: almacena la información del usuario obtenida del inicio de sesión social.

Puedes crear un mapa para hacer coincidir la información del usuario de tu perfil existente con los datos básicos y datos personalizados. Para el inicio de sesión social, necesitarás pasos adicionales para importar las identidades sociales, consulta la API de Vincular identidad social a usuario.

Mantener los IDs de usuario existentes

Por defecto, Logto genera un ID aleatorio para cada usuario creado a través del Management API. Si tu aplicación ya almacena IDs de usuario del proveedor de identidad anterior, puedes conservarlos pasando un id opcional en el cuerpo de la solicitud create user. Esto evita mantener una tabla de mapeo entre los IDs antiguos y nuevos.

El ID debe tener entre 1 y 128 caracteres y puede contener letras, números y _ - . @ : + = |. Esto cubre formatos comunes como auth0|5f7c8ec7c33c6c004bbafe82, google-oauth2|103547991597142817347, UUIDs, user_01H8MZ2QK3V4X5Y6Z7 y direcciones de correo electrónico. Los caracteres que no son válidos en rutas de URL (espacios, /, ?, #, %, \) son rechazados con 400, ya que el ID se usa en /api/users/{userId}. Si el ID ya está en uso, la solicitud falla con 422 user.id_already_in_use.

{
  "id": "auth0|5f7c8ec7c33c6c004bbafe82",
  "primaryEmail": "john.doe@example.com",
  "passwordAlgorithm": "Bcrypt",
  "passwordDigest": "$2b$10$..."
}

nota:

Los IDs de usuario personalizados solo son compatibles en Logto autogestionado. Logto Cloud rechaza las solicitudes que incluyen id con 501 request.feature_not_supported, porque los IDs de usuario se comparten entre inquilinos.

Hashing de contraseñas

Logto utiliza Argon2 para hashear la contraseña del usuario, y también admite otros algoritmos como MD5, SHA1, SHA256 y Bcrypt para facilitar la migración. Estos algoritmos se consideran inseguros, los hashes de contraseña correspondientes se migrarán a Argon2 en el primer inicio de sesión exitoso del usuario.

Si utilizas otros algoritmos de hash o salt, puedes establecer passwordAlgorithm en Legacy, esto te permite usar cualquier algoritmo de hash compatible con Node.js. Puedes encontrar la lista de algoritmos soportados en la documentación de Node.js crypto. En este caso, el passwordDigest será una cadena JSON que contiene el algoritmo de hash y otros parámetros específicos del algoritmo.

Formato Legacy general

El formato de la cadena JSON es el siguiente:

["hash_algorithm", ["argument1", "argument2", ...], "expected_hashed_value"]

Y puedes usar @ como marcador de posición para el valor real de la contraseña en los argumentos.

Por ejemplo, si usas SHA256 con un salt, puedes almacenar la contraseña en el siguiente formato:

["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"]

Esto equivale al siguiente código:

const hash = crypto.createHash('sha256');
// Concatenar el salt y la contraseña real
hash.update('salt123' + 'password123');
const expectedHashedValue = hash.digest('hex');

Soporte para PBKDF2

Logto admite específicamente PBKDF2.

Para migrar contraseñas hasheadas con PBKDF2, establece passwordAlgorithm en Legacy y da formato a passwordDigest de la siguiente manera:

["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"]

Los parámetros son:

• salt: El valor de salt usado en el hash original
• iterations: Número de iteraciones (por ejemplo, "1000")
• keylen: Longitud de la clave derivada en bytes (por ejemplo, "20")
• digest: La función hash utilizada (por ejemplo, "sha512", "sha256", "sha1")
• @: Marcador de posición para el valor real de la contraseña
• expected_hashed_value: El resultado esperado del hash como cadena hexadecimal

Ejemplo de payload de migración:

{
  "username": "john_doe",
  "primaryEmail": "john.doe@example.com",
  "passwordAlgorithm": "Legacy",
  "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]"
}

Soporte para Firebase scrypt

Logto también admite el algoritmo scrypt modificado utilizado por Firebase Authentication. Establece passwordAlgorithm en Legacy y da formato a passwordDigest de la siguiente manera:

[
  "firebase-scrypt",
  ["salt", "signer_key", "salt_separator", "rounds", "mem_cost", "@"],
  "expected_hashed_value"
]

Los parámetros son:

• salt: El salt del usuario de firebase auth:export
• signer_key, salt_separator, rounds, mem_cost: Los parámetros de hash de contraseña de tu proyecto, que se encuentran en la consola de Firebase en Authentication > Users > ⋮ > Password hash parameters
• @: Marcador de posición para el valor real de la contraseña
• expected_hashed_value: El passwordHash del usuario de la exportación, en base64 estándar. Si lees usuarios con el Firebase Admin SDK, convierte su base64 seguro para URL (-, _) a base64 estándar (+, /) primero.

passwordDigest está limitado a 256 caracteres, así que serialízalo como JSON compacto sin espacios (por ejemplo, con JSON.stringify).

Los usuarios importados en Firebase con un hash que no sea scrypt y que no hayan iniciado sesión desde entonces se exportan con passwordHash y salt vacíos. Importe esos usuarios con su hash original si aún lo tienes, o pídeles que restablezcan su contraseña.

Ejemplo de payload de migración:

{
  "username": "john_doe",
  "primaryEmail": "john.doe@example.com",
  "passwordAlgorithm": "Legacy",
  "passwordDigest": "[\"firebase-scrypt\",[\"42xEC+ixf3L2lw==\",\"jxspr8Ki0RYycVU8zykbdLGjFQ3McFUH0uiiTvC8pVMXAn210wjLNmdZJzxUECKbm0QsEmYUSDzZvpjeJ9WmXA==\",\"Bw==\",\"8\",\"14\",\"@\"],\"lSrfV15cpx95/sZS2W9c9Kp6i/LVgQNDNC/qzrCnh1SAyZvqmZqAjTdn3aoItz+VHjoZilo78198JAdRuid5lQ==\"]"
}

Pasos para migrar

1. Prepara los datos de usuario
   Primero debes exportar los datos de usuario de tu plataforma existente y luego mapear la información del usuario al esquema de usuario de Logto. Te recomendamos preparar los datos mapeados en formato JSON. Aquí tienes un ejemplo de los datos de usuario:

   [
     {
       "username": "user1",
       "passwordDigest": "password-encrypted",
       "passwordAlgorithm": "SHA256"
     },
     {
       "username": "user2",
       "passwordDigest": "password-encrypted",
       "passwordAlgorithm": "SHA256"
     }
   ]

2. Crea un tenant en Logto
   Necesitarás configurar un tenant en Logto. Puedes usar Logto Cloud o Logto OSS. Si aún no lo has hecho, consulta la guía Configura Logto cloud.

3. Configura la conexión con el Management API
   Usaremos el Management API para importar los datos de usuario, puedes consultar Management API para aprender cómo configurar la conexión en tu entorno de desarrollo.

4. Importa los datos de usuario
   Se recomienda preparar un script para importar los datos de usuario uno por uno, llamaremos a la API create user para importar los datos de usuario. Aquí tienes un ejemplo de script:

   const users = require('./users.json');
   
   const importUsers = async () => {
     for (const user of users) {
       try {
         await fetch('https://[tenant_id].logto.app/api/users', {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
             Authorization: 'Bearer [your-access-token]',
           },
           body: JSON.stringify(user),
         });
         // Dormir un momento para evitar el límite de tasa
         await new Promise((resolve) => setTimeout(resolve, 200));
       } catch (error) {
         console.error(`No se pudo importar el usuario ${user.username}: ${error.message}`);
       }
     }
   };
   
   importUsers();

Ten en cuenta que el endpoint de la API tiene límite de tasa, debes añadir una pausa entre cada solicitud para evitar el límite. Consulta nuestra página de límites de tasa para más detalles.

Si tienes una gran cantidad de datos de usuario (más de 100k usuarios), puedes contactarnos para aumentar el límite de tasa.

Recursos relacionados

Una guía general para migrar tu base de datos de usuarios existente a Logto