Anatomia do JWT: cabeçalho, carga útil e assinatura

Um token Web JSON (JWT) é um formato compacto de token seguro para URLs, definido na RFC 7519. Ele codifica reivindicações (afirmações sobre uma entidade) e uma assinatura criptográfica em uma única cadeia de caracteres, permitindo autenticação sem estado.

Um JWT tem o formato: base64url(header).base64url(payload).base64url(signature). O ponto separa as partes. O cabeçalho e a carga útil são legíveis (base64url, não criptografados). Apenas a assinatura tem natureza criptográfica.

O cabeçalho é um objeto JSON: {"alg":"HS256","typ":"JWT"}. alg especifica o algoritmo de assinatura (HS256, RS256, ES256, none). typ é sempre "JWT". Cabeçalhos adicionais incluem kid (ID da chave) para a seleção de chaves.

Reivindicações registradas padrão: iss (emissor), sub (sujeito), aud (público-alvo), exp (marca de tempo Unix de expiração), nbf (não válido antes de), iat (emitido em), jti (ID do JWT para revogação). Reivindicações personalizadas são quaisquer pares adicionais de chave e valor.

import base64, json token = "eyJ..." parts = token.split(".") header = json.loads(base64.urlsafe_b64decode(parts[0]+"==")) payload = json.loads(base64.urlsafe_b64decode(parts[1]+"==")) print(header, payload)

Para HS256: HMAC-SHA256(base64url(header)+"."+base64url(payload), secret). O receptor recalcula esse valor e o compara com a parte da assinatura. Se os valores coincidirem e o token não estiver expirado, ele será válido.

Para RS256: a chave privada assina a cadeia header.payload usando RSA-SHA256. Qualquer entidade que possua a chave pública pode verificar a assinatura sem a chave privada. As chaves públicas são distribuídas por meio de endpoints JWKS (conjuntos de chaves Web JSON), por exemplo, /.well-known/jwks.json.

Base64url substitui + por - e / por _, além de omitir o preenchimento com =. Isso torna os JWTs seguros em URLs, cabeçalhos HTTP e cookies sem codificação percentual. Os bytes brutos continuam não criptografados — apenas codificados.

A carga útil de um JWT é visível para qualquer pessoa que a decodifique com base64url. Nunca coloque segredos (senhas, números de Segurança Social) na carga útil de um JWT, a menos que use JWE (Criptografia Web JSON) com o algoritmo "enc" para obter criptografia real.

Defina exp para uma duração curta (15–60 minutos para tokens de acesso). JWTs de longa duração acumulam riscos — se forem roubados, continuarão válidos até expirarem. Use tokens de atualização (armazenados com segurança) para emitir novos tokens de acesso de curta duração.

Provedores de autenticação (Auth0, Keycloak, Google) publicam uma URL de JWKS. O verificador busca as chaves públicas por kid, armazena-as em cache e verifica as assinaturas sem contatar o emissor a cada solicitação. A rotação de chaves atualiza o endpoint de JWKS.

Qual parte de um JWT contém a assinatura criptográfica?

Um JWT é composto por três partes JSON codificadas em base64url: cabeçalho (algoritmo), carga útil (reivindicações) e assinatura. A carga útil é legível — não é criptografada. A seguir: escolha entre HS256 e RS256.