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	Escolha quando	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 as 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 arquivos que não podem ser mapeados para os 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 para dados básicos e dados personalizados. Para login social, serão necessários passos adicionais para importar as identidades sociais, consulte a API de Vincular identidade social ao usuário.

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, isso permite que você use 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');
// Adiciona o salt e a senha
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 utilizada (ex.: "sha512", "sha256", "sha1")
• @: Placeholder para o valor real da senha
• expected_hashed_value: O resultado esperado do hash 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\"]"
}

Etapas para migrar

1. Prepare os dados do usuário
   Você deve primeiro 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, vamos chamar a API criar usuário para importar os dados. 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),
         });
         // Aguarda um tempo para evitar limite de taxa
         await new Promise((resolve) => setTimeout(resolve, 200));
       } catch (error) {
         console.error(`Falha ao importar o 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 mais 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

Uma diretriz geral para migrar seu banco de dados de usuários existente para o Logto