Migração de usuários

O Logto suporta tanto a migração em massa quanto a migração just-in-time de usuários existentes de outro sistema de identidade. Este guia explica como importar usuários em massa através da Management API e o que considerar antes de migrar.

Escolha uma estratégia de migração

Estratégia	Quando escolher	Como funciona
Migração em massa	Você pode exportar os registros de usuários e hashes de senha em um formato que o Logto suporta.	Importe os usuários antes da mudança através da Management API, seguindo o restante deste guia.
Migração just-in-time	Você precisa verificar senhas contra o sistema existente, não pode exportar hashes de senha compatíveis ou deseja migrar usuários ativos gradualmente.	Configure uma Ação pós-verificação do primeiro fator. No primeiro login por senha do usuário, o Logto verifica as credenciais através da sua Ação, cria ou atualiza o usuário e armazena um novo hash de senha local.

A migração just-in-time mantém o serviço de autenticação legado no caminho da solicitação de login até que os usuários sejam migrados. Use um endpoint HTTPS rápido e confiável e mantenha-o disponível durante o período de migração.

Esquema do usuário

Antes de começarmos, vamos dar uma olhada no esquema do usuário no Logto. Existem 3 partes do esquema do usuário que você deve conhecer:

1. Dados básicos: são as informações básicas do perfil do usuário, você pode mapear os dados do seu perfil de usuário existente.
2. Dados personalizados: armazena informações adicionais do usuário, você pode usar isso para armazenar dados que não se encaixam nos dados básicos.
3. Identidades sociais: armazena as informações do usuário recuperadas do login social.

Você pode criar um mapa para corresponder as informações do usuário do seu perfil existente aos dados básicos e dados personalizados. Para login social, você precisará de etapas adicionais para importar as identidades sociais, consulte a API de Vincular identidade social ao usuário.

Manter IDs de usuários existentes

Por padrão, o Logto gera um ID aleatório para cada usuário criado através da Management API. Se seu aplicativo já armazena IDs de usuários do provedor de identidade anterior, você pode mantê-los passando um id opcional no corpo da requisição create user. Isso evita a necessidade de manter uma tabela de mapeamento entre os IDs antigos e novos.

O ID deve ter entre 1 e 128 caracteres e pode conter letras, números e _ - . @ : + = |. Isso cobre formatos comuns como auth0|5f7c8ec7c33c6c004bbafe82, google-oauth2|103547991597142817347, UUIDs, user_01H8MZ2QK3V4X5Y6Z7 e endereços de e-mail. Caracteres que não são válidos em caminhos de URL (espaço em branco, /, ?, #, %, \) são rejeitados com 400, já que o ID é usado em /api/users/{userId}. Se o ID já estiver em uso, a requisição falha com 422 user.id_already_in_use.

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

nota:

IDs de usuário personalizados são suportados apenas no Logto auto-hospedado. O Logto Cloud rejeita requisições que incluem id com 501 request.feature_not_supported, pois os IDs de usuário são compartilhados entre os tenants.

Hash de senha

O Logto utiliza Argon2 para hashear a senha do usuário, e também suporta outros algoritmos como MD5, SHA1, SHA256 e Bcrypt para facilitar a migração. Esses algoritmos são considerados inseguros; os hashes de senha correspondentes serão migrados para Argon2 no primeiro login bem-sucedido do usuário.

Se você estiver usando outros algoritmos de hash ou salt, pode definir o passwordAlgorithm como Legacy, o que permite usar qualquer algoritmo de hash suportado pelo Node.js. Você pode encontrar a lista de algoritmos suportados na documentação do Node.js crypto. Nesse caso, o passwordDigest será uma string JSON que contém o algoritmo de hash e outros parâmetros específicos do algoritmo.

Formato Legacy geral

O formato da string JSON é o seguinte:

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

E você pode usar @ como um placeholder para o valor real da senha nos argumentos.

Por exemplo, se você estiver usando SHA256 com um salt, pode armazenar a senha no seguinte formato:

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

Isso equivale ao seguinte código:

const hash = crypto.createHash('sha256');
// 'salt123' + 'password123'
hash.update('salt123' + 'password123');
const expectedHashedValue = hash.digest('hex');

Suporte a PBKDF2

O Logto suporta especificamente PBKDF2.

Para migrar senhas hasheadas com PBKDF2, defina o passwordAlgorithm como Legacy e formate o passwordDigest da seguinte forma:

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

Os parâmetros são:

• salt: O valor do salt usado na hash original
• iterations: Número de iterações (ex: "1000")
• keylen: Tamanho da chave derivada em bytes (ex: "20")
• digest: A função de hash usada (ex: "sha512", "sha256", "sha1")
• @: Placeholder para o valor real da senha
• expected_hashed_value: O hash esperado como uma string hexadecimal

Exemplo de payload de migração:

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

Suporte ao Firebase scrypt

O Logto também suporta o algoritmo scrypt modificado usado pelo Firebase Authentication. Defina passwordAlgorithm como Legacy e formate o passwordDigest da seguinte forma:

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

Os parâmetros são:

• salt: O salt do usuário exportado pelo firebase auth:export
• signer_key, salt_separator, rounds, mem_cost: Parâmetros de hash de senha do seu projeto, encontrados no console do Firebase em Authentication > Users > ⋮ > Password hash parameters
• @: Placeholder para o valor real da senha
• expected_hashed_value: O passwordHash do usuário exportado, em base64 padrão. Se você ler usuários com o Firebase Admin SDK, converta o base64 seguro para URL (-, _) para base64 padrão (+, /) primeiro.

O passwordDigest é limitado a 256 caracteres, então serialize como JSON compacto sem espaços (por exemplo, com JSON.stringify).

Usuários importados no Firebase com um hash diferente de scrypt que não fizeram login desde então são exportados com passwordHash e salt vazios. Importe-os com o hash original se ainda o tiver, ou peça para redefinirem a senha.

Exemplo de payload de migração:

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

Etapas para migrar

1. Prepare os dados dos usuários
   Primeiro, você deve exportar os dados dos usuários da sua plataforma existente e, em seguida, mapear as informações do usuário para o esquema de usuário do Logto. Recomendamos que você prepare os dados mapeados em formato JSON. Aqui está um exemplo dos dados do usuário:

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

2. Crie um tenant no Logto
   Você precisará configurar um tenant no Logto. Você pode usar tanto o Logto Cloud quanto o Logto OSS. Se ainda não fez isso, consulte o guia Configurar Logto cloud.

3. Configure a conexão com a Management API
   Usaremos a Management API para importar os dados dos usuários. Você pode consultar a Management API para aprender como configurar a conexão em seu ambiente de desenvolvimento.

4. Importe os dados dos usuários
   Recomenda-se preparar um script para importar os dados dos usuários um por um. Chamaremos a API create user para importar os dados dos usuários. Aqui está um exemplo 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),
         });
         // Aguarde um pouco para evitar limite de taxa
         await new Promise((resolve) => setTimeout(resolve, 200));
       } catch (error) {
         console.error(`Falha ao importar usuário ${user.username}: ${error.message}`);
       }
     }
   };
   
   importUsers();

Observe que o endpoint da API possui limite de taxa; você deve adicionar uma pausa entre cada requisição para evitar o limite. Consulte nossa página de limites de taxa para detalhes.

Se você tiver uma grande quantidade de dados de usuários (100k+ usuários), pode entrar em contato conosco para aumentar o limite de taxa.

Recursos relacionados

Um guia geral para migrar seu banco de dados de usuários existente para o Logto