JWKS no Node.js: valide e rotacione chaves JWT

JWKS no Node.js permite validar assinaturas de tokens usando um conjunto público de chaves em formato JSON Web Key Set. Provedores de identidade publicam uma URL de JWKS para que APIs obtenham as chaves correspondentes ao campo kid do JWT.

A validação segura exige mais que baixar uma chave. A aplicação deve fixar issuer, audience e algoritmos, usar cache com rotação, limitar requisições e impedir que o próprio token escolha uma URL arbitrária.

Formato JWKS

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-2026-01",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

O conjunto pode conter chaves atuais e anteriores durante a rotação.

Descobrindo a JWKS URI

Em OpenID Connect, o documento de discovery informa jwks_uri. A aplicação deve partir de um issuer configurado em allowlist e validar que o documento retornado possui o issuer esperado.

Usando jose

npm install jose

import { createRemoteJWKSet, jwtVerify } from 'jose';

const issuer = 'https://identity.example';
const jwks = createRemoteJWKSet(
  new URL('https://identity.example/.well-known/jwks.json')
);

const result = await jwtVerify(token, jwks, {
  issuer,
  audience: 'catalog-api',
  algorithms: ['RS256']
});

A biblioteca seleciona a chave por kid e mantém cache. Ainda assim, configure timeouts e restrições de rede no ambiente.

Fixe algoritmos

Não confie apenas no alg do cabeçalho. Declare a allowlist:

algorithms: ['RS256', 'ES256']

Inclua somente os algoritmos realmente usados pelo provedor.

Valide claims

A assinatura prova que a chave assinou o token, não que o token serve para sua API. Valide:

• iss;
• aud;
• exp;
• nbf quando presente;
• escopos ou permissões;
• tenant e subject conforme a política.

Seleção por kid

O campo kid identifica uma chave. Se não houver chave correspondente, atualize o conjunto uma vez, com rate limit. Não faça download ilimitado para cada token desconhecido.

Rotação de chaves

Durante a rotação, o provedor publica a chave nova antes de usá-la e mantém a antiga até os tokens expirarem. A API deve aceitar ambas durante a janela.

Evite fixar uma única chave manualmente por anos. Prefira JWKS com cache e atualização controlada.

Cache

Cache reduz latência e dependência do provedor. Defina:

• tempo de vida razoável;
• limite de chaves;
• atualização quando kid não existe;
• fallback para chaves ainda válidas durante indisponibilidade curta.

Não mantenha chaves antigas indefinidamente sem necessidade.

Cache-Control

O endpoint pode enviar cabeçalhos de cache. Respeite-os dentro de limites internos. Um provedor mal configurado não deve causar requisição por token nem cache eterno.

Proteção contra SSRF

Nunca leia jku ou outra URL do cabeçalho JWT e faça fetch automaticamente. A URL de chaves deve vir de configuração confiável ou discovery validado.

Multiple issuers

Para vários tenants, mantenha uma configuração por issuer aprovado:

const issuers = new Map([
  ['https://id-a.example', { audience: 'api-a', jwks: jwksA }],
  ['https://id-b.example', { audience: 'api-b', jwks: jwksB }]
]);

Leia o payload sem confiar apenas para selecionar um issuer candidato e depois execute validação completa. Limite o número de issuers configurados.

Timeout e limites

O fetch da JWKS deve ter timeout, limite de resposta e redirects restritos. O endpoint deve usar HTTPS e certificado válido.

Falha do provedor

Se a chave necessária já está em cache, continue validando. Se um kid novo aparece durante indisponibilidade, falhe fechado; aceitar sem validação não é opção.

Tokens sem kid

Quando o conjunto possui uma única chave compatível, algumas bibliotecas conseguem selecioná-la. Em produção, exija kid quando o provedor usa rotação e múltiplas chaves.

Tipos de chave

RSA usa n e e. EC usa curva e coordenadas. EdDSA depende de suporte do runtime e biblioteca. Não converta valores manualmente se uma biblioteca auditada já implementa o padrão.

Uso da chave

Verifique use: sig ou operações permitidas. Uma chave destinada a criptografia não deve ser usada automaticamente para assinatura.

Clock tolerance

Permita pequena tolerância para relógios, mantendo infraestrutura sincronizada:

clockTolerance: '5s'

Tolerância grande prolonga validade de tokens expirados.

Observabilidade

Monitore:

• cache hit e miss de chave;
• downloads de JWKS;
• latência e erros;
• kid desconhecido;
• algoritmo rejeitado;
• issuer ou audience inválidos;
• rotações detectadas;
• uso de chave antiga.

Não registre o token completo.

Testes

• assinatura válida;
• kid desconhecido seguido de refresh;
• algoritmo não permitido;
• issuer e audience incorretos;
• token expirado;
• rotação com chave antiga e nova;
• JWKS indisponível com cache;
• resposta enorme;
• URL não autorizada;
• múltiplos issuers.

Erros comuns

• aceitar jku do token;
• não fixar algoritmos;
• validar assinatura sem audience;
• fetch por requisição;
• refresh ilimitado para kid aleatório;
• não limitar redirects e tamanho;
• apagar chave antiga cedo demais;
• registrar tokens;
• falhar aberto quando o provedor cai.

Conclusão

JWKS no Node.js simplifica a distribuição e rotação de chaves públicas para JWT. A segurança depende de manter a URL sob controle e validar o contexto completo do token.

Use biblioteca consolidada, cache, rate limit de refresh, issuer e audience fixos. Trate chaves desconhecidas como falha de autenticação, não como motivo para aceitar o token.

Consulte a RFC 7517 sobre JSON Web Key e a documentação da biblioteca jose.