Migração de autenticação sem deslogar todo mundo: trocar o esquema de token em produção

Quando uma equipe decide trocar o esquema de autenticação, a conversa costuma girar em torno de biblioteca, algoritmo e formato: sai o segredo compartilhado, entra a assinatura assimétrica, sai a validade longa, entra o par de acesso curto e renovação rotativa. Tudo isso é código, e código se troca com um deploy. O que não se troca com deploy é a população de tokens já emitidos, que está guardada no armazenamento local de navegadores, no cofre de chaves de aplicativos móveis, em variáveis de ambiente de integrações de parceiros e em colunas de banco de sistemas que você nunca viu. Cada um desses tokens é uma promessa assinada que continua válida até expirar, e o servidor que para de reconhecê-la está quebrando a promessa de uma vez para todos.

A consequência prática é que a duração mínima da migração não é decidida pela equipe, e sim pela maior validade de token que já foi emitida. Se o token legado vive trinta dias, existe token legado legítimo circulando por trinta dias depois da última emissão, e qualquer plano que desligue o formato antigo antes disso está escolhendo deslogar gente. Existe ainda uma população que não segue a validade: o token de renovação de aplicativo móvel que o usuário abre uma vez por mês, e a credencial de integração que foi colada num arquivo de configuração e nunca mais tocada.

O incidente da abertura tem um segundo componente que costuma ser subestimado: o custo do login em massa. Verificar senha com bcrypt, scrypt ou Argon2 é caro de propósito, na ordem de dezenas a centenas de milissegundos de CPU por tentativa, porque isso encarece ataque de força bruta. Um serviço dimensionado para algumas centenas de logins por minuto não sustenta dezenas de milhares, e a mesma propriedade que protege contra ataque transforma o deslogamento em massa em indisponibilidade. Somam-se a isso o pico de redefinição de senha dos usuários que não lembram a própria senha e o custo de SMS de segundo fator, que aparece na fatura do mês seguinte.

A regra que evita o rollback impossível é a mesma de qualquer migração de esquema com tráfego ligado: primeiro todos os leitores aprendem o formato novo, só depois algum escritor começa a produzi-lo. No caso de token, leitor é todo serviço que valida, e escritor é o serviço que emite. Se a emissão do formato novo começa enquanto existe uma única instância, ou uma única versão alvo de rollback, que não sabe validá-lo, o usuário que recebeu o token novo é deslogado assim que cai nessa instância ou assim que o rollback acontece.

FASE 0  estado atual
        valida: legado            emite: legado

FASE 1  expandir (deploy de leitura, sem mudanca visivel)
        valida: legado + novo     emite: legado
        pre-requisito da fase 2: TODAS as instancias e a versao
        alvo de rollback aceitam os dois formatos

FASE 2  migrar
        valida: legado + novo     emite: novo   (clientes que entendem)
                                  emite: legado (endpoint antigo, apps antigos)
        troca silenciosa converte cada token legado no proximo contato
        rollback seguro: voltar para a FASE 1 nao desloga ninguem

FASE 3  drenar
        emissao legada desligada; populacao legada so decai
        espera minima = maior validade legada emitida + margem

FASE 4  contrair
        valida: novo              emite: novo
        segredo legado removido da configuracao e revogado

A fase 1 é a que mais gente pula, porque ela não entrega nada visível. Ela existe para que o rollback da fase 2 seja trivial: voltar para uma versão que aceita os dois formatos não afeta ninguém, enquanto voltar para a fase 0 desloga todo mundo que já foi convertido. Na prática, a fase 1 precisa ficar em produção tempo suficiente para que nenhuma versão anterior a ela continue candidata a rollback, o que significa pelo menos um ciclo completo de deploy e a remoção dos artefatos antigos do registro de implantação.

1. Publicar a chave pública nova no endpoint de chaves antes de assinar qualquer coisa com ela, porque serviços que fazem cache desse endpoint podem levar minutos ou horas para enxergá-la.
2. Implantar o validador duplo em todos os serviços que validam token, incluindo gateways, workers de fila e serviços internos que alguém esqueceu que também validam.
3. Confirmar por métrica, e não por inventário, que todas as instâncias em execução reportam suporte ao formato novo antes de ligar a emissão.
4. Ligar a emissão nova por coorte, começando por uma fração pequena de usuários, e observar a taxa de 401 por motivo e a taxa de login durante pelo menos um dia inteiro.
5. Manter a emissão legada disponível no endpoint antigo enquanto houver versão de cliente que só entende o formato antigo, e medir essa população por versão.

O validador que aceita dois formatos tem uma tentação perigosa: olhar o campo de algoritmo no cabeçalho do token e usar o que ele diz. Esse é o caminho para a confusão de algoritmo, uma vulnerabilidade conhecida em que o atacante pega a chave pública do esquema novo, que é pública por definição, e a usa como segredo para assinar um token com o algoritmo simétrico do esquema legado. Um validador que confia no cabeçalho vai tentar verificar esse token com a chave pública como se fosse segredo compartilhado, e a assinatura bate. Durante a convivência dos dois esquemas, a janela para esse erro está aberta justamente porque os dois algoritmos são aceitos ao mesmo tempo.

A defesa é inverter a fonte da verdade. O servidor mantém um mapa de chaves conhecidas, cada uma amarrada a um único algoritmo, e usa o cabeçalho do token apenas para escolher qual entrada do mapa consultar. O algoritmo passado para a verificação sai do mapa, numa lista de um elemento só, e o do token é apenas conferido contra ele. Assim a chave pública nunca é usada como segredo simétrico, porque não existe nenhuma entrada do mapa em que ela esteja associada a um algoritmo simétrico.

// auth/validador-duplo.js
// Aceita o formato legado (HS256, sem kid) e o novo (ES256, com kid)
// durante a convivencia. O algoritmo vem do servidor, nunca do token.
import { createHash } from 'node:crypto';
import { decodeProtectedHeader, importSPKI, jwtVerify } from 'jose';

const EMISSOR = 'https://auth.exemplo.com';
const AUDIENCIA = 'api';

// Chaves do esquema novo, indexadas por kid. Cada kid tem UM algoritmo.
const CHAVES_NOVAS = new Map([
  [
    '2026-09-es256',
    {
      esquema: 'novo',
      algoritmo: 'ES256',
      chave: await importSPKI(process.env.AUTH_CHAVE_PUBLICA_2026_09, 'ES256'),
      opcoes: { issuer: EMISSOR, audience: AUDIENCIA },
    },
  ],
]);

// O legado nao tinha kid, issuer nem audience. Ele so e aceito com o
// algoritmo que realmente usava e ate a data de corte planejada:
// ultima emissao legada + 30 dias de validade + margem.
const LEGADO = {
  esquema: 'legado',
  algoritmo: 'HS256',
  chave: new TextEncoder().encode(process.env.AUTH_SEGREDO_LEGADO),
  opcoes: {},
  aceitarAte: Date.parse(process.env.AUTH_LEGADO_ACEITAR_ATE || '2026-11-15T00:00:00Z'),
};

export class TokenInvalido extends Error {
  constructor(motivo) {
    super(motivo);
    this.motivo = motivo; // vira rotulo de metrica: 401 por motivo
  }
}

export const impressaoDoToken = (token) =>
  createHash('sha256').update(token).digest('hex');

function resolverEntrada(cabecalho) {
  if (cabecalho.kid) return CHAVES_NOVAS.get(cabecalho.kid) || null;
  if (cabecalho.alg !== LEGADO.algoritmo) return null;
  if (Date.now() >= LEGADO.aceitarAte) return null;
  return LEGADO;
}

export async function validarToken(token) {
  let cabecalho;
  try {
    cabecalho = decodeProtectedHeader(token);
  } catch {
    throw new TokenInvalido('formato');
  }

  const entrada = resolverEntrada(cabecalho);
  if (!entrada) throw new TokenInvalido('chave_desconhecida');

  try {
    const { payload } = await jwtVerify(token, entrada.chave, {
      algorithms: [entrada.algoritmo], // lista de um so elemento
      clockTolerance: 30,
      ...entrada.opcoes,
    });

    return {
      sujeito: payload.sub,
      esquema: entrada.esquema,
      expiraEm: payload.exp * 1000,
      // O legado pode nao ter jti: a impressao do proprio token o substitui.
      impressao: payload.jti || impressaoDoToken(token),
    };
  } catch (erro) {
    throw new TokenInvalido(erro.code || 'assinatura');
  }
}

Três detalhes desse código fazem diferença em produção. O primeiro é a data de corte do legado estar no próprio validador, lida de configuração: o caminho antigo se fecha sozinho na data planejada, sem depender de alguém lembrar de fazer um deploy de remoção, e a data pode ser adiada sem mudar código se a métrica mostrar população residual. O segundo é o motivo da rejeição virar rótulo de métrica, porque durante a migração a pergunta mais importante é quantos 401 são de token expirado, que é normal, e quantos são de chave desconhecida ou assinatura inválida, que indicam uma instância sem a chave nova ou um cliente mandando algo inesperado. O terceiro é a tolerância de relógio: tokens de quinze minutos tornam a diferença de relógio entre servidores relevante de um jeito que tokens de trinta dias nunca tornaram.

Esperar a população legada expirar sozinha funciona, mas desperdiça a oportunidade de convertê-la. A troca silenciosa aproveita o próximo contato do cliente atualizado: quando ele apresenta um token legado válido ao endpoint de renovação, o servidor devolve um par novo, e o usuário nunca percebe que houve migração. O ponto delicado é que o token legado precisa deixar de ser trocável depois da troca, senão um token roubado continua gerando pares novos indefinidamente, e é aqui que a maioria das implementações desloga usuários legítimos.

O motivo é concorrência do próprio cliente. Um usuário com três abas abertas, ou um aplicativo que dispara quatro requisições em paralelo ao voltar do segundo plano, apresenta o mesmo token legado várias vezes no mesmo segundo. Se a primeira requisição consome o token e as outras três recebem rejeição por reuso, o cliente interpreta essa rejeição como sessão inválida e manda o usuário para a tela de login. O mesmo problema existe na rotação de token de renovação no esquema novo, e a solução é a mesma nos dois casos: uma janela de graça em que requisições concorrentes com o mesmo token recebem exatamente o mesmo par, em vez de um par cada uma ou de uma rejeição.

// auth/troca-legado.js
// Converte um token legado em par novo, uma unica vez, tolerando
// requisicoes concorrentes do mesmo cliente dentro da janela de graca.
import { createClient } from 'redis';
import { TokenInvalido, validarToken } from './validador-duplo.js';
import { emitirPar } from './emissor.js';

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

const JANELA_DE_GRACA_S = 120; // abas e requisicoes paralelas do mesmo cliente
const RESERVA_S = 10; // se o processo morrer no meio, a reserva expira sozinha
const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms));

export async function trocarTokenLegado(token, tentativa = 0) {
  const sessao = await validarToken(token);
  if (sessao.esquema !== 'legado') throw new TokenInvalido('nao_e_legado');

  const chave = `troca:${sessao.impressao}`;
  const chavePar = `${chave}:par`;
  const restanteS = Math.max(1, Math.ceil((sessao.expiraEm - Date.now()) / 1000));

  // 1) Quem conseguir a reserva emite. NX garante um unico emissor.
  const reservado = await redis.set(chave, 'pendente', { NX: true, EX: RESERVA_S });

  if (reservado) {
    const par = await emitirPar({ sujeito: sessao.sujeito, origem: 'troca_legado' });
    // Par e marca de consumo gravados juntos: quem vir 'trocado' acha o par.
    await redis
      .multi()
      .set(chavePar, JSON.stringify(par), { EX: JANELA_DE_GRACA_S })
      .set(chave, 'trocado', { EX: restanteS })
      .exec();
    return par;
  }

  // 2) Outra requisicao com o mesmo token chegou antes. Espera o resultado.
  for (let i = 0; i < 20; i += 1) {
    const estado = await redis.get(chave);

    if (estado === 'trocado') {
      const par = await redis.get(chavePar);
      if (par) return JSON.parse(par); // dentro da graca: o MESMO par
      // Fora da graca, reuso do token legado e sinal de copia do token.
      throw new TokenInvalido('legado_ja_trocado');
    }

    if (estado === null) {
      // A reserva expirou sem concluir (processo morreu): tenta assumir.
      if (tentativa >= 2) break;
      return trocarTokenLegado(token, tentativa + 1);
    }

    await esperar(100);
  }

  throw new TokenInvalido('troca_em_andamento'); // cliente deve repetir em breve
}

A reserva curta de dez segundos e a marca de consumo longa são duas travas com objetivos diferentes. A reserva evita que duas instâncias emitam pares diferentes para o mesmo token ao mesmo tempo, e expira rápido para que uma falha no meio da emissão não bloqueie aquele usuário para sempre. A marca de consumo dura até o token legado expirar e é o que impede um token copiado de continuar gerando sessões. Gravar o par e a marca na mesma transação é o que torna a leitura consistente: nenhuma requisição concorrente vê o estado de trocado sem conseguir achar o par durante a janela de graça.

O par fica guardado por dois minutos no armazenamento compartilhado, e isso é uma decisão de segurança consciente, não um descuido. A alternativa seria rejeitar as requisições concorrentes, o que desloga usuário legítimo, ou emitir um par para cada uma, o que multiplica sessões e torna a detecção de reuso impossível. Dois minutos de retenção num armazenamento que já guarda sessões, com tempo de vida curto e acesso restrito, é um custo pequeno. Se o reuso aparecer depois da janela, o comportamento mais seguro é revogar também a família de tokens gerada pela troca, porque não há como saber qual das duas cópias é a legítima.

O contrato implícito de um token não é apenas ser aceito pelo servidor. Clientes e intermediários criam dependências de formato, tamanho e conteúdo que ninguém documentou, e a migração é o momento em que todas elas aparecem ao mesmo tempo. Um token assinado com curva elíptica e com mais claims costuma ser maior do que o legado, e um token opaco no lugar de um JWT deixa de ser decodificável, e cada uma dessas mudanças quebra alguma coisa que dependia da forma antiga.

A primeira linha tem uma consequência que muda o plano inteiro. Um aplicativo que não sabe lidar com o formato novo não pode receber o formato novo, e isso significa que a emissão legada precisa continuar existindo no endpoint antigo enquanto essa versão do aplicativo estiver em uso. A emissão passa a ser decidida pela capacidade do cliente, informada por um cabeçalho de versão ou pelo próprio endpoint chamado, e a fase de drenagem só começa quando a versão antiga cai abaixo de um limiar aceitável ou quando uma atualização obrigatória é publicada. É por isso que a data de corte do legado é uma decisão de produto além de técnica.

Integrações de parceiros merecem um canal próprio. Para elas, o token não circula por sessão de usuário, e sim por credencial de serviço, e a conversão silenciosa não acontece porque o parceiro não chama o endpoint de renovação. O caminho é tratar o novo esquema como uma versão do contrato de integração, com data anunciada, período de convivência medido em meses e uma métrica por parceiro mostrando quem ainda usa o formato antigo, para que a conversa aconteça antes do corte e não no chamado aberto depois dele.

O corte do legado deve ser uma decisão tomada por número e não por calendário, e os números precisam existir desde a fase 1. A métrica central é a população legada ativa: quantos sujeitos distintos apresentaram token legado válido nas últimas vinte e quatro horas, quebrado por versão de cliente e por parceiro. Essa curva deve cair de forma previsível depois que a emissão legada para, e o formato dela diz muito: queda rápida seguida de platô indica um grupo que não se converte sozinho, como uma versão antiga do aplicativo ou uma integração esquecida, e esse grupo precisa de ação direta antes do corte.

O indicador de logins por minuto é o que detecta o problema mais rápido, porque ele reage em minutos enquanto a população legada reage em dias. Um alerta sobre ele, comparando com o mesmo horário da semana anterior, precisa estar ativo antes de qualquer fase que mude emissão ou validação, e o critério de reversão da fase precisa estar escrito antes de ela começar. Uma migração de autenticação que só descobre o deslogamento em massa pelo volume de chamados no suporte já perdeu a primeira hora do incidente.

1. Confirmar que a emissão legada está desligada há pelo menos a maior validade legada emitida, contada a partir da última emissão real registrada e não da data do deploy.
2. Confirmar que a população legada ativa está abaixo do limiar combinado com produto, com a lista nominal de parceiros restantes já contatados.
3. Antecipar a data de corte no validador em ambiente de homologação e rodar a suíte de testes de ponta a ponta com as versões de cliente ainda suportadas.
4. Aplicar o corte em produção por configuração, sem deploy de código, mantendo por alguns dias a possibilidade de adiar a data se o indicador de logins reagir.
5. Remover o segredo legado da configuração e revogá-lo na origem, porque um segredo que ninguém usa e que continua válido é só superfície de ataque.
6. Remover o código do caminho legado num deploy separado, depois de um ciclo inteiro sem nenhuma validação legada registrada.