Claim (JWT)

Um claim é um par nome/valor no payload de um JWT que afirma algo sobre o sujeito do token. Os claims são propriedades JSON; o payload é um objeto JSON deles. Claims padrão definidos na RFC 7519 §4:

• iss — Issuer: quem criou o token.
• sub — Subject: sobre quem é o token (tipicamente um ID de usuário).
• aud — Audience: para quem o token é destinado. Pode ser uma string ou array.
• exp — Expiry: segundos Unix após os quais o token deve ser rejeitado.
• iat — Issued At: segundos Unix quando o token foi criado.
• nbf — Not Before: segundos Unix antes dos quais o token é inválido.
• jti — JWT ID: um identificador único para rastreamento de revogação.

Além do conjunto padrão, as aplicações adicionam seus próprios claims: role, email, tenant_id, permissions, etc. A RFC 7519 não restringe a aparência dos claims customizados, embora a IANA mantenha um registro de nomes conhecidos para evitar colisões.

Três classes de claims vale distinguir: registrados (os sete acima, gerenciados pela IANA), públicos (registrados na IANA ou com namespace sob um URI para evitar colisões) e privados (mutuamente acordados entre emissor e consumidor; sem namespace).

Decodifique e inspecione cada claim em um JWT com nosso decodificador JWT. Ele exibe os claims padrão separadamente e mostra o tempo até a expiração em relação à hora atual da sua máquina.

Namespace de claims customizados — a prática padrão: quando uma aplicação adiciona claims customizados que podem ser incorporados em um token compartilhado entre fornecedores, prefixe-os com um URI de sua propriedade. Auth0 usa https://yourdomain.com/claims/role; AWS Cognito usa cognito:groups. Nomes simples como role ou permissions são convenientes, mas correm o risco de colidir com claims futuros registrados na IANA e com as convenções de outros fornecedores. O OpenID Connect especifica certos nomes convencionais (email, name, given_name, family_name, picture, locale) com significados estáveis em provedores de identidade — estes são seguros de usar como estão em qualquer fluxo compatível com OIDC. Referência: Registro de Claims de JSON Web Token da IANA.

Exemplo prático: validando exp e nbf

Considere um payload JWT {"sub":"42","iat":1716220800,"exp":1716224400,"nbf":1716220800}. O token foi emitido no timestamp Unix 1716220800 (2024-05-20 16:00:00 UTC), é válido imediatamente e expira em 1716224400 (2024-05-20 17:00:00 UTC) — um tempo de vida de uma hora. Um verificador correto lê o tempo Unix atual, rejeita o token se now ≥ exp (com pequena tolerância opcional, tipicamente 30-60 segundos, para absorver desvio de relógio entre serviços) e rejeita se now < nbf. A RFC 7519 §4.1.4 exige que o processamento de exp “DEVE” levar em conta o desvio de relógio, mas deixa a tolerância ao implementador. Uma tolerância de 60 segundos é o padrão de fato do setor; jose, jsonwebtoken e pyjwt usam todos janelas configuráveis de 0-60s.

Por que isso importa: as implicações de segurança

A maioria dos incidentes de segurança JWT rastreia omissões na validação de claims, não falhas criptográficas. O comunicado Auth0 CVE-2018-0114 de 2018 documentou bibliotecas que verificavam a assinatura mas ignoravam exp, permitindo a repetição de tokens roubados indefinidamente. Vários frameworks foram lançados com verificadores padrão que ignoram aud, permitindo que um token cunhado para um serviço seja aceito por outro no mesmo domínio de confiança. Melhores práticas: sempre verifique o conjunto completo de claims padrão aplicáveis (iss, aud, exp, nbf, mais assinatura e lista de permissões de algoritmos) — cada biblioteca expõe esses como opções de construtor ou chamada de verificação, e o custo de habilitá-los é essencialmente zero. Referência: RFC 8725 — Melhores práticas atuais de JSON Web Token.