Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.replit.com/llms.txt

Use this file to discover all available pages before exploring further.

Se o seu app já tem um sistema de autenticação funcionando e um banco de dados de usuários reais, trocar pelo Clerk Auth não é apenas uma mudança de código — é uma migração de dados. Sem um plano deliberado, cada linha existente na sua tabela users se tornará estranha ao Clerk: novas contas são provisionadas no primeiro login, nenhuma delas corresponde aos seus dados históricos, e clientes que retornam parecem ter “perdido” suas contas. Há realmente apenas duas coisas que você precisa acertar.
Esta página é para desenvolvedores que já rodam um app com sua própria autenticação. Se você está começando um novo app, consulte a visão geral do Clerk Auth — nenhuma migração é necessária.

​
1. Importe seus usuários existentes para o Clerk

Cada usuário ativo no seu app precisa existir como um usuário Clerk antes do Clerk Auth entrar em operação. No mínimo, cada importação precisa incluir:
  • E-mail (obrigatório)
  • Metadados de perfil disponíveis: nome, status de verificação, qualquer outra coisa que você queira visível no painel Auth
  • Hash de senha: o hash de senha existente do usuário
  • Algoritmo de hash: o algoritmo/formato desse hash, exatamente como o Clerk espera
O algoritmo de hash é a parte que é fácil de errar. O Clerk aceita apenas um conjunto definido de formatos de hash de senha, e cada um tem um identificador de string específico (bcrypt, scrypt_firebase, argon2i, pbkdf2_sha256, etc.). Veja a lista completa e o formato exato de digest que cada um requer na referência da API de Criação de Usuário do Clerk. Esta etapa requer mais do que um prompt de uma linha. O Agent que conduz a migração precisa de uma compreensão profunda de como as senhas são hasheadas no seu código atual — qual biblioteca, quais parâmetros (fator de custo, layout de salt, pepper, etc.) e como isso mapeia para um dos algoritmos suportados pelo Clerk. Um prompt bem formulado se parece com algo assim: 
Leia meu código de autenticação existente e identifique exatamente como as senhas são hasheadas
(biblioteca, algoritmo, parâmetros e como o valor armazenado é formatado).
Em seguida, escreva um script de importação único que, para cada usuário na minha tabela users,
chame a API Backend do Clerk com e-mail, metadados de perfil, o digest de senha no formato
exato que o algoritmo Clerk correspondente espera, e o valor correto de `passwordHasher`.
Diga-me qual algoritmo Clerk você escolheu e por quê antes de executar.
Se o seu esquema de hash não mapear claramente para nenhum dos algoritmos suportados pelo Clerk, os usuários importados não conseguirão fazer login com sua senha existente. Nesse caso, importe-os sem um digest e envie um e-mail de redefinição de senha na transição.

​
2. Resolva usuários Clerk de volta para seus IDs de usuário existentes

Uma vez que os usuários importados fazem login, cada solicitação autenticada carrega uma identidade Clerk. Seu servidor precisa mapear essa identidade de volta para a linha na sua tabela users — caso contrário, o ID de usuário do Clerk não corresponderá a nenhuma das suas chaves estrangeiras existentes (orders.user_id, documents.owner_id, etc.) e os dados históricos parecerão perdidos. O Clerk gerenciado pela Replit torna isso simples: quando você importa um usuário com seu ID existente como o externalId do usuário Clerk, esse valor é automaticamente escrito nas claims da sessão como sessionClaims.userId. Seu middleware só precisa preferir isso em vez do ID de usuário bruto do Clerk: 
import { getAuth } from "@clerk/express";

const requireAuth = (req: any, res: any, next: any) => {
  const auth = getAuth(req);
  const userId = auth?.sessionClaims?.userId || auth?.userId;
  if (!userId) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  req.userId = userId;
  next();
};
Com esse padrão:
  • Usuários importados resolvem para seu users.id existente via sessionClaims.userId — todos os seus dados históricos permanecem vinculados.
  • Usuários novos (que se cadastraram após a transição e não têm externalId) recorrem a auth.userId, que é seu ID de usuário do Clerk. Use o ID de usuário do Clerk como chave primária para essas novas linhas, ou crie uma linha no primeiro login e vincule-a de volta.

​
É isso

Todo o resto — manter sua autenticação antiga rodando em paralelo, executar um teste com contas reais, monitorar a criação de usuários duplicados após a transição, desativar o sistema antigo — é higiene padrão de migração e não é específico do Clerk Auth.

​
Recursos adicionais