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 seu app já tem um sistema de autenticação funcionando e um banco de dados de usuários reais, trocar para o 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 torna estranha ao Clerk: novas contas são provisionadas no primeiro login, nenhuma delas se alinha com seus dados históricos, e os clientes que retornam parecem ter “perdido” suas contas. Há realmente apenas duas coisas que você precisa acertar.
Esta página cobre apenas a migração de uma solução de autenticação personalizada (sua própria tabela de usuários, hash de senha, sessões, etc.) para o Clerk Auth. Não é um guia para mover um app do Replit Auth para o Clerk Auth — orientações oficiais para esse caminho de migração estão por vir.Se você está começando um novo app, veja 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 usuário Clerk antes do Clerk Auth entrar em funcionamento. No mínimo, cada importação precisa incluir:
  • Email (obrigatório)
  • Metadados de perfil disponíveis: nome, status de verificação, qualquer outra coisa que você queira visível no painel Auth
  • Digest de senha: o hash de senha existente do usuário
  • Hasher de senha: o algoritmo/formato desse hash, exatamente como o Clerk espera
O hasher é a parte mais 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 Create User 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 completa de como as senhas são hasheadas na sua base de código atual — qual biblioteca, quais parâmetros (fator de custo, layout de salt, pepper, etc.) e como isso se mapeia em um dos hashers 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 de usuários, chame a API Backend do Clerk com email, metadados de perfil,
o digest de senha no formato exato que o hasher Clerk correspondente espera, e o
valor correto de `passwordHasher`. Diga-me qual hasher Clerk você escolheu e por quê
antes de executá-lo.
Se seu esquema de hash não se mapeia claramente para nenhum dos hashers 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 email de redefinição de senha no momento da migração.

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

Depois que os usuários importados fizerem login, cada requisiçã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 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 pelo Replit torna isso simples: quando você importa um usuário com seu ID existente como externalId do usuário Clerk, esse valor é automaticamente escrito nas claims da sessão como sessionClaims.userId. Seu middleware só precisa preferir esse valor sobre o ID de usuário Clerk bruto: 
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 este padrão:
  • Usuários importados resolvem para seu users.id existente via sessionClaims.userId — todos os seus dados históricos permanecem vinculados.
  • Usuários completamente novos (que se cadastraram após a migração e não têm externalId) voltam para auth.userId, que é seu ID de usuário Clerk. Use o ID de usuário 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 funcionando em paralelo, executar um teste com contas reais, monitorar a criação de usuários duplicados após a migração, desativar o sistema antigo — é higiene padrão de migração e não é específico do Clerk Auth.

​
Recursos adicionais