ADR-003 — Clerk como Provedor de Autenticação

Data: 2026-03
Status: Ativo

Contexto

O CRM precisava de autenticação para usuários administrativos (não clientes). Requisitos:

Multi-tenancy (organizações separadas)
Convites por email
Reset de senha
Sessões seguras
Sem implementar do zero

Alternativas consideradas

Alternativa	Motivo de descarte
JWT próprio + bcrypt	Implementação de sessão/refresh/revogação é complexa e propensa a bugs de segurança
Auth0	Mais caro, configuração mais complexa
NextAuth	Bom para Next.js, mas o backend separado precisaria revalidar tokens — mais complexo
Supabase Auth	Acoplaria ao Supabase — não queríamos lock-in de banco
Clerk	Integração Next.js nativa, multi-tenancy built-in, webhook lifecycle, SDK simples — escolhido

Decisão

Clerk como provedor de identidade. O CRM não implementa autenticação própria.

JWT verificado via clerkClient.verifyToken(token) no ClerkAuthGuard
Banco local tem tabela User como mirror de dados do Clerk (não armazena senha)
Convites gerenciados pelo Clerk (email automático)
ClerkBootstrapService sincroniza membros na inicialização

Consequências

Positivas:

Sem necessidade de implementar reset de senha, sessões, refresh tokens
Integração Next.js com @clerk/nextjs é madura e fácil
Multi-tenancy nativo (Organization no Clerk espelha Organization no CRM)
Webhooks confiáveis via Svix com verificação HMAC

Negativas:

Lock-in no Clerk — migrar seria custoso
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY precisa estar disponível no build do frontend (requisita Azure Key Vault)
Custo adicional (SaaS) conforme crescimento do número de organizações

Configuração necessária

Clerk Dashboard → API Keys → copiar CLERK_SECRET_KEY e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
Clerk Dashboard → Webhooks → apontar para https://apicrm.galdix.com.br/webhooks/clerk
URLs de sign-in/sign-up configuradas para domínio do CRM

Referências de implementação

backend/src/config/users/clerk-auth.guard.ts
backend/src/config/users/clerk-bootstrap.service.ts
backend/src/modules/users/users.controller.ts