JWT — Padrões de Propriedades (Claims) | API | CSharp

• Estrutura e Padronização de Claims | API | CSharp

---

Visão Geral

Um JWT (JSON Web Token) é definido pela RFC 7519 e possui três partes:

• Header
• Payload
• Signature

Formato estrutural:

BASE64URL(HEADER) + "." + BASE64URL(PAYLOAD) + "." + BASE64URL(SIGNATURE)

O foco desta documentação são as propriedades do payload (claims).

---

Classificação das Claims

As propriedades do payload são divididas formalmente em três categorias:

• Registered Claims (Padronizadas)
• Public Claims
• Private Claims

---

Registered Claims

Claims oficialmente definidas pela especificação. Não são obrigatórias, mas possuem semântica padronizada.

Claim	Tipo	Descrição
iss	string	Identifica o emissor do token
sub	string	Identificador principal do token (ex: userId)
aud	string ou array	Destinatários autorizados
exp	number (timestamp UNIX)	Data de expiração
nbf	number (timestamp UNIX)	Válido a partir de
iat	number (timestamp UNIX)	Data de emissão
jti	string	Identificador único do token

Exemplo

{
  "iss": "https://auth.sistema.com",
  "sub": "15000",
  "aud": "api-gateway",
  "exp": 1710000000,
  "iat": 1709996400,
  "jti": "uuid-v4"
}

Observações técnicas:

• exp, iat e nbf devem ser timestamps UNIX em segundos
• aud pode ser string ou array
• jti é recomendado para controle de revogação

---

Public Claims

Claims customizadas registradas publicamente para evitar colisões de nome.

Recomendação técnica:

• Utilizar namespace próprio (URI controlada)

Exemplo:

{
  "https://meusistema.com/roles": ["admin", "editor"]
}

Esse padrão evita conflitos entre diferentes serviços distribuídos.

---

Private Claims

Claims internas da aplicação. Não seguem padronização formal.

Exemplo típico:

{
  "userId": 15000,
  "nomeUsuario": "TESTE_PRECISAO",
  "codigoEstacao": 25000,
  "userType": 5
}

Riscos arquiteturais:

• Colisão de nomes entre serviços
• Crescimento excessivo do payload
• Exposição indevida de dados sensíveis

⚠ JWT não deve armazenar dados confidenciais (senha, segredo, dados sensíveis).

---

Header Padrão

O header contém metadados sobre o token.

Exemplo:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-001"
}

Campos comuns:

• alg → Algoritmo de assinatura (HS256, RS256, ES256)
• typ → Tipo do token (geralmente "JWT")
• kid → Identificador da chave usada na assinatura

---

Estrutura Recomendada para APIs Modernas

Modelo recomendado para ambientes com microserviços:

{
  "iss": "https://auth.meusistema.com",
  "sub": "15000",
  "aud": ["api-gateway", "mobile-app"],
  "exp": 1710000000,
  "iat": 1709996400,
  "jti": "uuid-v4",
  "scope": "read write",
  "roles": ["admin"],
  "tenant": "empresa-xyz"
}

Boas práticas arquiteturais:

• sub deve ser imutável e único
• Tokens devem ser pequenos
• Evitar payload inflado
• Validar aud, iss, exp e nbf
• Implementar tolerância a clock skew na validação

---

Validação Estrita

Checklist mínimo de validação:

• Verificar assinatura
• Validar algoritmo permitido (whitelist)
• Conferir iss
• Conferir aud
• Validar exp
• Validar nbf
• Conferir integridade estrutural

Exemplo conceitual de validação (Node.js):

import jwt from "jsonwebtoken";

const token = req.headers.authorization?.split(" ")[1];

const payload = jwt.verify(token, publicKey, {
  algorithms: ["RS256"],
  issuer: "https://auth.meusistema.com",
  audience: "api-gateway"
});

---

Erros Arquiteturais Comuns

• Aceitar qualquer algoritmo (alg none attack)
• Não validar aud
• Usar HS256 com chave compartilhada em múltiplos serviços
• Armazenar informações sensíveis no payload
• Tokens com expiração excessivamente longa

---