Saltar al contenido principal

Migración de usuarios

Logto admite la migración manual de usuarios existentes desde otra plataforma. Esta guía te mostrará cómo importar usuarios existentes a través de la Management API (Management API) y hablará sobre aspectos que debes considerar antes de migrar.

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 se pueden asociar con los datos básicos.
  3. Identidades sociales: almacena la información del usuario obtenida del inicio de sesión social.

Puedes crear un mapeo para asociar 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.

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ñ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, lo que 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 general Legacy​

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');
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 al passwordDigest de la siguiente manera:

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

Los parámetros son:

  • salt: El valor de salt utilizado 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​

  1. Prepara los datos de usuario
    Primero debes exportar los datos de usuario de tu plataforma actual 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 Configurar Logto cloud.

  3. Configura la conexión con la Management API
    Usaremos la Management API (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 de crear usuario 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),
          });
          // Sleep for a while to avoid rate limit
          await new Promise((resolve) => setTimeout(resolve, 200));
        } catch (error) {
          console.error(`Failed to import user ${user.username}: ${error.message}`);
        }
      }
    };

    importUsers();

Ten en cuenta que el endpoint de la API tiene límite de velocidad; debes añadir una pausa entre cada solicitud para evitar el límite. Consulta nuestra página de límites de velocidad 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 velocidad.

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