Ir para o conteúdo

ADR-0001 - Rotação de Chaves JWT com kid

Status: Proposto
Data: 2026-03-08

1. Contexto

Atualmente os JWTs de autenticação da plataforma são assinados com HS256 usando segredo único de ambiente (JWT_SECRET), sem kid.

Risco principal: - comprometimento de segredo implica risco amplo sobre tokens emitidos no período; - ausência de mecanismo de rotação gradual sem impacto operacional.

2. Decisão

Adotar assinatura de JWT de autenticação com suporte explícito a rotação de chaves:

  • incluir kid no header do JWT;
  • manter keyset ativo com múltiplas chaves válidas simultaneamente;
  • usar uma chave de escrita (ativa) e N chaves de leitura (janela de transição);
  • validar assinatura por lookup da chave via kid.

Modelo inicial: - algoritmo: HS256 (compatível com estado atual); - estrutura de configuração: mapa kid -> secret; - chave ativa separada: JWT_ACTIVE_KID; - fallback sem kid: desabilitar após janela de migração.

3. Alternativas consideradas

  1. Manter segredo único (estado atual)
    Rejeitada por não suportar rotação segura e gradual.

  2. Blacklist agressiva de access token sem key rotation
    Rejeitada por atacar sintoma operacional e não resolver gestão segura de chaves.

  3. Migrar imediatamente para assimétrico (RS256/EdDSA)
    Válida no médio prazo, mas aumenta escopo da mudança inicial. Pode ser fase 2 após kid + keyset.

4. Consequências

Positivas: - rotação de chave sem downtime; - redução de risco em incidente de exposição de segredo; - melhor trilha de governança de credenciais.

Custos: - aumento de complexidade de configuração; - necessidade de runbook operacional de rotação; - testes adicionais para compatibilidade de tokens antigos.

5. Plano de migração

  1. Introduzir keyset e JWT_ACTIVE_KID no backend.
  2. Emitir tokens novos com kid.
  3. Aceitar tokens sem kid por janela controlada.
  4. Rotacionar chave ativa e manter chave anterior em leitura.
  5. Encerrar suporte a token sem kid.

Critérios de aceite: - token emitido contém kid; - backend valida token antigo e novo durante janela de transição; - rotação documentada com rollback; - testes automatizados cobrindo múltiplas chaves e chave inválida.