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:

Dados básicos: são as informações básicas do perfil do usuário, você pode corresponder os dados do seu perfil de usuário existente.
Dados personalizados: armazena informações adicionais do usuário, você pode usar isso para armazenar arquivos que não podem ser correspondidos aos dados básicos.
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 de usuário 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 de 1 a 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, isso 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');
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 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\"]"
}

Etapas para migrar

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"
  }
]
```
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.
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.

Importe os dados dos usuários É recomendado preparar um script para importar os dados dos usuários um por um, vamos chamar a API create user 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),
      });
      // 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 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.

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

Escolha uma estratégia de migração​

Esquema do usuário​

Manter IDs de usuários existentes​

Hash de senha​

Formato Legacy geral​

Suporte a PBKDF2​

Etapas para migrar​

Recursos relacionados​