Header (JWT/JWS)

O header de um JWT (ou JWS) é o primeiro segmento separado por ponto, um objeto JSON codificado em base64url que descreve as propriedades de assinatura do token. Decodifique-o e você obtém um pequeno objeto JSON tipicamente contendo 2-5 campos.

Campos de header padrão (RFC 7515 §4):

• alg — algoritmo. Obrigatório. Ex.: HS256, RS256, ES256, ou none.
• typ — tipo. Convencionalmente "JWT" quando o payload é um conjunto de claims JWT.
• kid — ID de chave. Permite ao receptor escolher a chave correta de um conjunto de chaves quando o emissor rotaciona chaves.
• jwk / jku — JSON Web Key embutida ou URL para uma. Menos comum; sensível à segurança se usado.
• cty — tipo de conteúdo. Usado quando o payload é uma estrutura JOSE aninhada (ex.: um JWE dentro de um JWS).

Exemplo prático. Um header decodificado para:

{ "alg": "RS256", "typ": "JWT", "kid": "2024-q1-key" }

declara que o token está assinado com RS256 (RSA + SHA-256), é um JWT (portanto o payload é um conjunto de claims) e foi assinado com a chave identificada por 2024-q1-key no diretório de chaves do emissor.

Nota crítica de segurança: nunca confie apenas no campo alg. Verifique se o algoritmo corresponde ao que sua chave é adequada. O ataque de confusão de alg funciona passando um token assinado com HS256 (HMAC) usando sua chave pública RSA como o segredo HMAC — se seu verificador confia cegamente no alg, ele aceita a falsificação.

A codificação base64url compacta do header o torna inspecionável por humanos: colar o primeiro segmento separado por ponto de qualquer JWT em um decodificador base64url revela o algoritmo e a referência de chave em segundos. Este é o ponto de entrada de toda sessão de depuração JWT — se o header decodificar como lixo, o token está malformado; se decodificar para um objeto JSON que você não reconhece, o emissor mudou algo.

Quando e por que isso importa

O header JWT importa toda vez que um serviço verifica um token. A cadeia clássica de CVE: um verificador aceita o campo alg pelo valor de face e deixa um token especificando "alg": "none" passar sem nenhuma verificação de assinatura. Esse bug foi lançado em bibliotecas de produção tão recentemente quanto 2015 (CVE-2015-9235, afetando o node-jsonwebtoken do Auth0). A defesa é impor, na chamada de verificação, o algoritmo exato que a biblioteca deve aceitar — ex.: jwt.verify(token, key, { algorithms: ['RS256'] }) — e nunca confiar no header para escolher o algoritmo. Uma segunda classe de bug, o ataque de confusão de alg, explora bibliotecas que selecionam automaticamente HMAC vs RSA com base no header: o atacante entrega ao verificador um token que afirma HS256, mas assina com a chave pública RSA (que é publicada) usada como segredo HMAC. O verificador valida contra a chave pública e aceita a falsificação. Ambos os bugs são problemas de confiança no header. Para novas integrações JWT, audite a chamada de verificação e verifique se ela fixa o algoritmo. Referência: OWASP — Folha de dicas de JSON Web Token.

O header kid na rotação de chaves em produção: em qualquer sistema do mundo real que emite tokens em escala, a chave de assinatura precisa ser rotacionada periodicamente — a cada 90 dias é uma política comum. O campo kid permite ao emissor publicar múltiplas chaves simultaneamente (chaves antigas para tokens em trânsito, novas chaves para emissões recentes) e o verificador escolhe a correta a partir de um endpoint JWKS. O padrão de rotação padrão: anuncie a nova chave no JWKS enquanto ainda assina com a antiga, aguarde uma vida útil do token, mude a emissão para a nova chave, aguarde mais uma vida útil, depois remova a chave antiga do JWKS. O campo kid é o que torna isso elegante — sem ele, a rotação de chaves requer uma transição sincronizada de corte.

Como é o vetor de ataque jku / x5u: algumas implementações permitem que o header aponte para uma URL arbitrária onde a chave de verificação supostamente reside. Um atacante que define jku para uma URL que ele controla pode apresentar qualquer chave que quiser e o verificador a utilizará. A orientação moderna (RFC 8725, melhores práticas JOSE) é rejeitar jku/x5u completamente ou impor uma lista de permissões de URLs confiáveis. Novas integrações JWT não devem depender de localização de chave controlada pelo header. Referência: RFC 8725 — Melhores Práticas Atuais para JSON Web Token.