Blog

Rotação de chave de API e de segredo de webhook sem derrubar a integração

UNIFOKAL7 min de leituraProduto e integração

Trocar credencial só é indolor com uma janela em que as duas valem. A ordem do deploy, a telemetria que autoriza revogar e os gatilhos que obrigam a rotacionar.

Existem duas formas de trocar uma credencial. Na primeira, alguém revoga a chave atual, cria outra e sai correndo para atualizar as configurações antes que o telefone toque. Na segunda, a chave nova nasce ao lado da antiga, as duas funcionam por um tempo, e a antiga só é revogada quando ninguém mais a usa. A diferença entre as duas é a diferença entre um incidente e uma manutenção que ninguém percebeu.

A rotação é uma dessas tarefas que todo mundo concorda que precisa acontecer e quase ninguém ensaia. Aí ela chega pelo pior caminho: um segredo apareceu num repositório público, uma pessoa com acesso saiu da empresa, um log guardou o cabeçalho de autorização inteiro. Nessa hora, a pergunta prática não é se deve rotacionar, é se dá para rotacionar sem parar o cadastro.

Este texto trata do mecanismo que torna a resposta positiva: a janela de sobreposição, e o que ela exige do produto dos dois lados, na chave de API e no segredo que assina webhook.

Por que a troca instantânea derruba a integração

Revogar e criar parece atômico na interface, mas o sistema é distribuído e a mudança não chega em todo lugar ao mesmo tempo. Entre revogar a antiga e a nova valer de fato, existem instâncias que ainda não recarregaram a configuração, processos em execução que leram a chave na inicialização, jobs agendados com valor em cache, filas com trabalho que já estava em voo e um cache de segredo com tempo de vida próprio.

Cada uma dessas coisas continua tentando com o valor antigo, e todas passam a receber recusa de autenticação. O sintoma é feio porque é intermitente: parte do tráfego funciona, parte falha, e a hipótese inicial do time costuma ser instabilidade do fornecedor, não a troca que acabou de ser feita.

No caminho do webhook a assimetria é ainda maior. Quem assina é o fornecedor; quem verifica é você. Trocar o segredo de um lado sem que o outro conheça o novo valor transforma toda entrega em assinatura inválida, e as entregas rejeitadas não somem: elas entram em retentativa e voltam, com mais volume, contra um receptor que continua recusando.

A janela de sobreposição dos dois lados

O remédio é o mesmo nos dois casos, com mecânicas diferentes.

Na chave de API, a sobreposição é ter duas credenciais válidas simultaneamente. Cada uma com identificador próprio, cada uma com sua própria trilha de uso. O servidor aceita ambas enquanto durar a janela, e quem integra troca o valor no seu cofre com calma, no seu ritmo de deploy, sem coordenação de relógio com ninguém.

No segredo de webhook, a sobreposição acontece dentro da assinatura. O fornecedor calcula o HMAC, definido pela RFC 2104, uma vez com o segredo antigo e uma vez com o novo, e envia as duas assinaturas no mesmo cabeçalho. O receptor aceita a entrega se qualquer uma casar com algum dos segredos que ele conhece. Assim ninguém precisa acertar o instante da virada: durante a janela, tanto o receptor que já atualizou quanto o que ainda não atualizou conseguem validar.

Quem verifica precisa fazer a sua parte, que é escrever a verificação como laço sobre os segredos ativos, e não como comparação com um único valor. É uma mudança pequena, mas ela precisa existir antes da primeira rotação, e não durante. O mesmo vale para os detalhes de assinatura tratados em como receber webhooks com segurança.

A ordem do deploy

A sequência importa mais do que a ferramenta. Uma rotação sem susto tem quatro passos, nessa ordem:

  1. Criar a credencial nova, sem tocar na antiga. Nesse momento nada mudou para ninguém, e o passo é reversível: se algo der errado, basta apagar a que acabou de nascer.
  2. Publicar o novo valor nos dois lados. No cofre de segredos da aplicação, na configuração do ambiente, no receptor de webhook. Aqui a antiga ainda funciona, então o deploy pode falhar e ser refeito sem consequência.
  3. Observar o uso da antiga cair a zero. Não é uma formalidade, é o passo que autoriza o próximo. Enquanto houver tráfego com a chave antiga, existe alguma coisa que ninguém lembrou de atualizar.
  4. Revogar a antiga, e só então. A revogação é o único passo destrutivo, e ele acontece depois da evidência, não antes.

Esse desenho é o mesmo de qualquer mudança compatível para trás: introduzir o novo, conviver, remover o velho. Vale a mesma disciplina descrita em versionamento de API e mudanças que quebram integração, inclusive na parte de anunciar o prazo da janela em vez de encurtá-la por conveniência.

Observar o uso cair a zero exige telemetria

O passo 3 é onde a maioria dos processos desmorona, porque a informação necessária não existe. Sem telemetria por credencial, "ninguém mais usa a antiga" é uma crença, e a revogação vira aposta.

O mínimo útil por credencial é curto: data e hora do último uso, contador de requisições numa janela recente e, se possível, os endereços de origem observados. Com isso, a decisão de revogar deixa de ser opinião. O último uso há três semanas, com contador zerado desde o deploy, é evidência. O último uso há dois minutos é a resposta de que alguma instância ficou para trás, e geralmente aponta qual.

Vale lembrar que "zero requisições hoje" não é o mesmo que "zero uso". Integrações com rotina mensal, relatório de fechamento, job de conciliação: tudo isso pode usar a credencial em intervalos longos. A janela de observação precisa ser maior que o maior intervalo entre usos legítimos, ou a revogação vai encontrar o job justamente na virada do mês.

Um cuidado de privacidade fecha o assunto: essa trilha de uso é registro operacional, e o critério de sempre se aplica, sem carregar dado pessoal desnecessário para dentro do log, como discutido em auditoria de logs e dados pessoais.

Quando rotacionar, e por que a chave não volta a aparecer

Existem dois tipos de gatilho. Os reativos são óbvios e urgentes: segredo exposto em repositório, log ou captura de tela; saída de pessoa que tinha acesso ao cofre; suspeita de comprometimento de máquina; fim de contrato com fornecedor que detinha a credencial. Nesses casos a janela de sobreposição encolhe de propósito, porque o risco de manter a antiga viva supera o risco de derrubar o que ficou para trás.

O gatilho proativo é o calendário. A publicação NIST SP 800-57 Part 1 Revision 5, do National Institute of Standards and Technology, trata isso pelo conceito de criptoperíodo: toda chave tem um intervalo de tempo durante o qual seu uso permanece autorizado, e definir esse intervalo faz parte da gestão da chave, não é um detalhe operacional. Na prática, adotar um prazo declarado, ainda que generoso, transforma a rotação em rotina ensaiada, e é a rotina que faz a rotação de emergência funcionar quando ela for necessária.

Falta um detalhe de produto que parece incômodo e é proposital: a chave só aparece uma vez, no momento da criação. Depois disso o sistema guarda apenas um resumo criptográfico, e o valor original não pode ser exibido de novo. Isso não vem de norma nenhuma, é decisão de engenharia, a mesma que se aplica a senha: guardar o que serve para conferir e não o que serve para usar. E ela tem uma consequência direta neste assunto: quem perdeu o valor não tem como recuperá-lo, e a única saída é rotacionar. Uma plataforma que consegue mostrar sua chave de novo está guardando o valor de forma reversível, o que é bem pior do que o incômodo de criar outra.

Por fim, registre quem rotacionou e quando, com autor identificado e horário. Rotação é ação privilegiada: sem trilha, ninguém consegue responder mais tarde se aquela troca de terça-feira foi manutenção planejada ou o primeiro movimento de um invasor que já estava dentro.

Fontes citadas