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 usuario 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 por contraseña del usuario, Logto verifica las credenciales a través de 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:

Datos básicos: es la información básica del perfil de usuario, puedes hacer coincidir los datos de tu perfil de usuario existente.
Datos personalizados: almacena información adicional del usuario, puedes usar esto para guardar archivos que no puedan coincidir con los datos básicos.
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, por favor consulta la API de Vincular identidad social a usuario.

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. Esos algoritmos se consideran inseguros, los hashes de contraseñas 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 compatibles 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');
// Comentario: Concatenar el salt y la contraseña antes de hashear
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\"]"
}

Pasos para migrar

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"
  }
]
```
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.
Configura la conexión con el Management API
Usaremos el Management API para importar los datos de usuario, puedes consultar el Management API para aprender cómo configurar la conexión en tu entorno de desarrollo.

Importa los datos de usuario
Se recomienda preparar un script para importar los datos de usuario uno por uno, llamaremos a la API de crear usuario para importar los datos. 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),
      });
      // Esperar 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. Por favor revisa 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.

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

Elige una estrategia de migración​

Esquema de usuario​

Hashing de contraseñas​

Formato Legacy general​

Soporte para PBKDF2​

Pasos para migrar​

Recursos relacionados​