RFC 7519 · JSON Web Signature

Introdução ao JWT

JSON Web Token (JWT) é um padrão aberto (RFC 7519) para representar claims como uma string compacta e segura para URL. É muito usado com OAuth 2.0 e OpenID Connect, mas o formato é genérico: quem tiver o material de verificação correto pode checar a assinatura e interpretar os claims — dentro dos limites de chaves e relógios.

Esta página explica como um JWT é construído, como ler cada parte e quais garantias você deve — e não deve — esperar só do token.

header.payload.signature

Forma compacta: três segmentos Base64URL, separados por pontos.

Serialização compacta e codificação

Na forma usual (JSON Web Signature, JWS), um JWT tem três segmentos separados por pontos: header, payload e assinatura. Os dois primeiros são objetos JSON em Base64URL (não Base64 clássica): muitas vezes sem padding e com caracteres seguros para URL.

Base64URL não é criptografia. Header e payload são legíveis para quem tem a string. A assinatura prova que as duas primeiras partes foram produzidas por quem controla a chave; não oculta o conteúdo.

Estrutura de um JWT

Cada segmento tem um papel na forma compacta JWS:

Payload

Objeto JSON com claims: sujeito, janela de validade, audiência e campos específicos da aplicação. Objetos aninhados são permitidos quando o emissor define.

Assinatura

Valor criptográfico sobre os bytes de "header.payload" (os dois segmentos codificados e o ponto), usando o algoritmo do header e segredo compartilhado (HMAC) ou chave privada assimétrica (RSA, ECDSA, EdDSA).

Claims: o que há no payload

Claims são pares nome/valor. O significado depende do contexto, mas o RFC 7519 define nomes registrados para interoperar.

Claims registrados

Exemplos: iss, sub, aud, exp, nbf, iat, jti. exp e nbf são timestamps Unix; validá-los corretamente exige relógio confiável no verificador.

Claims públicos

Nomes podem ser registrados na IANA. Continuam sendo convenções até produtor e consumidor concordarem.

Claims privados

Nomes combinados entre emissor e consumidor (ex.: papéis internos). Evite colidir com nomes registrados salvo controle total dos dois lados.

Algoritmos em resumo

O valor alg no header define como a assinatura é calculada. Escolher o modelo errado afeta quem pode verificar e como segredos são compartilhados.

HMAC (HS*): um segredo compartilhado assina e verifica. Simples para um serviço, mas todo verificador precisa do segredo.
RSA ou ECDSA/EdDSA: o emissor assina com chave privada; verificadores usam a pública (muitas vezes via JWKS). Adequado a microsserviços e clientes sem segredo de assinatura.
O algoritmo "none" não deve ser aceito em produção: permitiria tokens sem assinatura se mal configurado. Rejeite algoritmos desconhecidos ou desativados.

Segurança: confiança, privacidade e validação

Uma assinatura válida mostra que o token foi emitido por quem controla a chave e que header e payload não foram alterados. Por si só não cifra nada.

Não coloque senhas, API keys ou segredos de longa duração no payload. Para confidencialidade além da assinatura, use TLS e considere JWE — outro formato e fluxo.

Servidores devem validar a assinatura com a chave ou JWKS esperados, checar exp (e geralmente nbf), aplicar aud e iss quando a arquitetura exige, e usar vidas curtas e refresh quando apropriado.

Usos comuns

JWTs costumam ser usados para:

Representar identidade e autorização (tokens bearer, ID tokens no OpenID Connect)
Propagar identidade ou delegação entre serviços
Modelar sessão em clientes com armazenamento seguro e estratégias de refresh
Carregar escopos OAuth 2.0 ou claims customizados em gateways e resource servers

Limites práticos

Restrições úteis ao projetar com JWTs:

Tamanho: tokens costumam ir em cabeçalhos HTTP; payloads grandes aumentam latência e podem bater em limites de proxy.
Revogação: um JWT puramente sem estado não revoga instantaneamente sem infra extra (listas de negação, introspecção ou vidas muito curtas).
Deriva de relógio: validação de exp e nbf depende de relógios razoavelmente sincronizados entre emissores e verificadores.