Referência para desenvolvedores JWT

Referência de Claims JWT

Ao depurar JWT, leio cada claim no contexto: quem emitiu, para quem foi emitido, quando vale e quais dados de autorização a aplicação entende.

48 / 48

Claims JWT registradas

iss

Emissor

stringRFC 7519 §4.1.1

Identifica quem emitiu o JWT.

Validação: Comparar exatamente com um issuer previamente confiado pela aplicação.

sub

Sujeito

stringRFC 7519 §4.1.2

Identifica o sujeito representado pelo JWT dentro do namespace do issuer.

Validação: Interpretar somente no namespace do issuer depois de validá-lo.

aud

Audience

string | string[]RFC 7519 §4.1.3

Identifica os destinatários pretendidos do JWT.

Validação: Exigir a audience esperada pelo resource server.

exp

Expiração

NumericDateRFC 7519 §4.1.4

Horário após o qual o JWT não deve ser aceito.

Validação: Rejeitar após exp permitindo apenas pequena tolerância de relógio configurada.

nbf

Não antes de

NumericDateRFC 7519 §4.1.5

Horário antes do qual o JWT não deve ser aceito.

Validação: Rejeitar antes de nbf, exceto pela tolerância configurada.

iat

Emitido em

NumericDateRFC 7519 §4.1.6

Horário em que o JWT foi emitido.

Validação: Usar em políticas de idade/vida útil e rejeitar valores futuros implausíveis.

jti

ID JWT

stringRFC 7519 §4.1.7

Identificador único do JWT.

Validação: Combinar com estado do servidor apenas quando replay ou revogação exigirem unicidade.

Identidade e ID Token OpenID Connect

azp

Parte autorizada

stringOIDC Core §2

Identifica a parte para a qual o ID Token foi emitido.

Validação: Verificar quando houver múltiplas audiences ou a política do cliente exigir.

nonce

Nonce

stringOIDC Core §2

Vincula um ID Token à solicitação de autenticação do navegador/cliente.

Validação: Comparar exatamente com o nonce salvo para a solicitação de autorização.

auth_time

Hora de autenticação

NumericDateOIDC Core §2

Momento em que ocorreu a autenticação do usuário.

Validação: Usar quando max_age ou reautenticação dependerem da idade da autenticação.

acr

Classe de contexto de autenticação

stringOIDC Core §2

Classe de contexto de autenticação alcançada.

Validação: Aceitar somente níveis de assurance reconhecidos explicitamente pela aplicação.

amr

Métodos de autenticação

string[]OIDC Core §2

Métodos realmente usados para autenticar o usuário.

Validação: Não inferir assurance de valores desconhecidos; seguir a semântica do issuer.

at_hash

Hash do Access Token

stringOIDC Core §3.1.3.6

Valor derivado de hash que vincula um Access Token a um ID Token.

Validação: Validar quando o flow/response type OIDC exigir.

c_hash

Hash do código de autorização

stringOIDC Core §3.3.2.11

Valor derivado de hash que vincula um código de autorização a um ID Token.

Validação: Validar quando o response type OIDC exigir.

s_hash

Hash de state

stringOIDC FAPI / registered claim

Vincula state a uma resposta assinada em determinados perfis OIDC/FAPI.

Validação: Validar somente quando o perfil OIDC/FAPI ativo exigir.

sid

ID de sessão

stringOpenID Connect Session Management

Identifica uma sessão do OpenID Provider.

Validação: Tratar como metadata de sessão do issuer, não como ID global do usuário.

name

Nome completo

stringOIDC Core §5.1

Nome completo de exibição do usuário.

Validação: Dado de perfil; não usar como identificador estável de autorização.

given_name

Nome

stringOIDC Core §5.1

Nome do usuário.

Validação: Dado de apresentação; considerar localização.

family_name

Sobrenome

stringOIDC Core §5.1

Sobrenome do usuário.

Validação: Não assumir unicidade.

middle_name

Nome do meio

stringOIDC Core §5.1

Nome do meio do usuário.

Validação: Tratar como dado opcional de perfil.

nickname

Apelido

stringOIDC Core §5.1

Apelido do usuário.

Validação: Usar apenas para apresentação.

preferred_username

Usuário preferido

stringOIDC Core §5.1

Nome de usuário curto preferido.

Validação: Não assumir unicidade global nem imutabilidade.

profile

URL de perfil

URL stringOIDC Core §5.1

URL da página de perfil.

Validação: Validar tratamento da URL antes de renderizar links.

picture

URL da imagem

URL stringOIDC Core §5.1

URL da imagem de perfil.

Validação: Tratar como conteúdo remoto não confiável ao renderizar.

website

URL do site

URL stringOIDC Core §5.1

URL do site do usuário.

Validação: Tratar como dado de perfil não confiável.

email

E-mail

stringOIDC Core §5.1

Endereço de e-mail preferido.

Validação: Só tratar como verificado se email_verified=true e o issuer for confiável.

email_verified

E-mail verificado

booleanOIDC Core §5.1

Indica se o issuer verificou o controle do e-mail.

Validação: Confiar apenas com issuer e método de verificação conhecidos.

gender

Gênero

stringOIDC Core §5.1

Valor de gênero fornecido pelo issuer.

Validação: Minimizar coleta quando o dado não for necessário.

birthdate

Data de nascimento

stringOIDC Core §5.1

Data de nascimento do usuário.

Validação: Dado sensível; não usar como fator de autenticação.

zoneinfo

Fuso horário

stringOIDC Core §5.1

Identificador de fuso horário.

Validação: Usar apenas para apresentação/preferências.

locale

Localidade

BCP 47 stringOIDC Core §5.1

Preferência de localidade/idioma.

Validação: Usar para apresentação, não para decisões de confiança.

phone_number

Número de telefone

stringOIDC Core §5.1

Número de telefone preferido.

Validação: Só tratar como verificado se phone_number_verified=true e o issuer for confiável.

phone_number_verified

Telefone verificado

booleanOIDC Core §5.1

Indica se o issuer verificou o controle do número.

Validação: Interpretar conforme a política e método de verificação do issuer.

address

Endereço postal

objectOIDC Core §5.1

Objeto estruturado de endereço postal.

Validação: Validar campos aninhados antes de exibir e tratar como dado sensível.

updated_at

Atualização do perfil

NumericDateOIDC Core §5.1

Momento da última atualização do perfil.

Validação: Usar somente como metadata de atualidade do perfil.

Access Token OAuth e autorização

client_id

ID do cliente

stringRFC 9068 §2.2

Identifica o cliente OAuth associado ao Access Token.

Validação: Comparar apenas se a política do resource server depender de um cliente específico.

scope

Scopes OAuth

space-delimited stringRFC 9068 §2.2.3 / RFC 8693

Permissões delegadas associadas ao Access Token.

Validação: Autorizar apenas scopes conhecidos pelo recurso e aplicáveis à audience.

roles

Papéis

string[]RFC 9068 §2.2.3.1 / RFC 7643

Valores de papel usados para autorização.

Validação: Definir semântica issuer/resource e rejeitar papéis desconhecidos por padrão.

groups

Grupos

string[]RFC 9068 §2.2.3.1 / RFC 7643

Associação a grupos usada em decisões de autorização.

Validação: Não assumir nomes ou hierarquias iguais entre issuers.

entitlements

Direitos

string[]RFC 9068 §2.2.3.1 / RFC 7643

Direitos ou privilégios atribuídos ao sujeito.

Validação: Mapear explicitamente cada entitlement para uma ação permitida.

cnf

Confirmação

objectRFC 7800

Informações de confirmação para chave proof-of-possession.

Validação: Validar de fato o método de confirmação exigido pelo token/perfil.

act

Ator

objectRFC 8693 §4.1

Identifica o ator efetivo em delegação ou impersonation.

Validação: Distinguir ator e sujeito em autorização e auditoria.

may_act

Pode atuar

objectRFC 8693 §4.4

Identifica partes autorizadas a agir pelo sujeito.

Validação: Usar apenas com política explícita de delegação/token exchange.

Autorização privada / fornecedor

permissions

Permissões

string[]Private claim

Lista privada de ações permitidas pela aplicação.

Validação: Definir issuer, audience e semântica de cada permissão privada.

role

Papel

string | string[]Private claim

Convenção privada para um ou vários papéis.

Validação: Não assumir equivalência com roles; mapear por issuer.

tenant

Tenant

stringPrivate claim

Convenção privada para routing de tenant ou organização.

Validação: Nunca estabelecer confiança do issuer só pelo tenant; conferir contexto autenticado.

org_id

ID da organização

stringPrivate claim

Identificador de organização comum em modelos SaaS.

Validação: Tratar como valor específico do issuer e exigir membership do recurso separadamente.

token_use

Uso do token

stringVendor/private claim

Convenção de fornecedor para distinguir uso access/identity do token.

Validação: Usar apenas se documentado pelo issuer; preferir regras padrão typ/profile.