Chaves de assinatura JWT
Os pares de chaves com que um ambiente assina, os três estados pelos quais passam, e como rotacionar sem quebrar um token vivo.
Cada ambiente tem as suas próprias chaves de assinatura, no Console em Autenticação → Chaves de assinatura. Elas assinam tanto os access tokens que seus usuários carregam quanto os id tokens que o OAuth server emite — um conjunto só, um JWKS só, porque quem verifica confia num issuer e espera um lugar só de onde buscar.
Os três estados
Cada chave está em um de três estados:
Em usoassinaA chave com que os tokens novos são assinados. Exatamente uma por ambiente.
Em esperaverificaPublicada e capaz de verificar, esperando assumir. Nada é assinado com ela ainda.
Usada antesverificaPublicada e capaz de verificar, não assina mais.
RevogadarecusadaFora do JWKS e não aceita mais. Fica guardada, para você poder trazê-la de volta.
Toda chave que não esteja revogada é publicada no JWKS. É justamente para isso que serve o terceiro estado: um token assinado instantes antes de uma troca precisa continuar funcionando até expirar, e tirar a chave dele antes da hora recusaria requisições perfeitamente válidas.
Algoritmos
ES256padrãoECDSA na curva P-256. Chaves pequenas, assinaturas curtas, e a escolha a menos que algo force outra.
RS256RSA, no mínimo 2048 bits. Use quando uma biblioteca cliente ou uma integração mais antiga só fala RSA.
EdDSAEd25519. A mais rápida de verificar; confira antes se sua biblioteca suporta, porque o suporte é menos universal que nos outros dois.
Os identificadores são os registrados — ES256 e RS256 na
RFC 7518, EdDSA na
RFC 8037 — então uma biblioteca que lê
o header alg sabe o que fazer sem configuração sua.
Rotacionando uma chave
A rotação tem quatro passos de propósito, não um, porque a parte lenta não está nas nossas mãos: clientes guardam o JWKS em cache, e uma chave não pode começar a assinar antes que eles a tenham visto.
Adicione uma chave. Ela entra em espera — publicada, verificando, assinando nada. Gere uma, ou importe uma chave privada que você já tem em formato JWK.
Espere. O suficiente para os clientes buscarem o JWKS de novo. Quanto tempo é decisão sua, e depende do tempo de cache de quem verifica seus tokens.
Promova. Os tokens novos passam a ser assinados com ela a partir daquele momento. A que estava em uso cai para "usada antes" na mesma escrita, então nada que ela assinou quebra.
Espere de novo, desta vez pelos tokens. Um token assinado pela chave antiga vale até o próprio vencimento — nada o invalida antes — então a espera é um tempo de vida de access token.
Aí revogue a chave antiga. Nada revoga por você: revogar é a única forma de fazer os tokens dela pararem de ser aceitos, e fazer isso antes da hora recusa tokens que ainda estão perfeitamente válidos.
A chave em uso não pode ser revogada. Promova outra primeiro — o ambiente nunca fica sem nada com que assinar.
Voltando atrás numa rotação
Revogar é reversível. Uma chave revogada ou usada antes pode ser restaurada, o que a devolve para espera — publicada e verificando de novo — e dali você pode promovê-la, fazendo o ambiente voltar a assinar com a chave anterior.
É isso que torna uma rotação segura de tentar. Se algo lá na frente não tiver pegado a chave nova, você volta em vez de correr para frente.
Excluindo uma chave
Uma chave revogada pode ser excluída, o que remove ela e a metade privada de vez. Depois disso não há como restaurar, então vale deixá-la revogada tempo suficiente para ter certeza de que nada mais precisa dela. Só uma chave revogada pode ser excluída — não existe caminho direto de assinando para sumida.
Promover, revogar e excluir uma chave exigem sessão elevada. Você vai confirmar quem é antes da mudança valer, igual a qualquer outra ação sensível.
Importando a sua própria chave
Se você já tem um par de chaves — porque outro provedor emitiu, ou porque sua infraestrutura gera — cole a chave privada como JWK ao adicionar. Ela é guardada criptografada e não sai de lá; só a metade pública é servida.
A chave precisa trazer o componente privado, chaves RSA precisam de no mínimo 2048 bits, e chaves Edwards precisam usar Ed25519. Qualquer outra coisa é recusada em vez de guardada funcionando pela metade.