JWT explicado de verdade: claims, assinatura e expiração

Entenda como funciona um JWT, o que são claims como sub, iss, aud e exp, e quais cuidados tomar ao usar tokens em APIs.

15 de junho de 202610 min de leitura

JWT (JSON Web Token) virou o formato padrão de access token e ID token em APIs modernas. Três partes base64 separadas por ponto: header, payload, signature. Parece transparente — e é aí que muita gente só faz atob() no browser e acha que autenticou. JWT não é criptografia; é um payload assinado (ou cifrado, no caso de JWE).

Anatomia de um token

Header:  { "alg": "RS256", "typ": "JWT" }
Payload: { "sub": "user-123", "iss": "https://auth.example.com",
            "aud": "my-api", "exp": 1710003600, "roles": ["ADMIN"] }
Signature: RSASSA-PKCS1-v1_5 sobre header.payload

Claims que você precisa validar

iss (issuer) — quem emitiu; deve bater com seu Authorization Server
aud (audience) — para qual API/client o token foi emitido
sub (subject) — identificador estável do usuário
exp / nbf — expiração e validade temporal
iat — emitido em; útil para detectar tokens reutilizados

Assinatura e JWKS

Com RS256, a API busca chaves públicas via JWKS endpoint do issuer, verifica a assinatura e só então confia no payload. Rotação de chaves exige cache com TTL curto e fallback quando kid muda.

Quando JWT funciona bem

APIs stateless com validação local de token
Microsserviços que confiam no mesmo issuer
Tokens de curta duração + refresh token no backend

Erros comuns

Confiar no payload sem validar assinatura
Aceitar algoritmo HS256 com secret fraco compartilhado em 12 serviços
Ignorar exp ou usar clock skew infinito
Colocar PII ou dados sensíveis no payload (JWT não é secreto)
Access token com validade de dias "para não expirar sessão"
Não revogar refresh quando usuário muda senha

Como o Gatekeeper ID ajuda

A SDK Spring Boot valida JWT via JWKS do tenant, extrai roles/permissions e aplica RBAC antes do controller. Você não reimplementa parser, clock skew nem rotação de chaves — configura application.yml e protege endpoints.

Contexto de protocolo: OAuth2 vs OpenID Connect.

Conclusão

JWT é contrato entre issuer e resource server. Trate validação como código crítico de segurança — ou use biblioteca/SDK mantida que já implementa RFC 7519 corretamente.