C# Academy · Aula

Estrutura e declarações de JWT

Entenda o cabeçalho, a carga útil e a assinatura.

Estrutura e declarações de JWT é uma aula grátis de C# Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de C# Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de C# Academy inclui 4 aulas no total.

O que é um JWT

Um token Web JSON (JWT) é um formato compacto de token seguro para URL, usado para transmitir declarações com segurança entre duas partes. No ASP.NET Core, é a forma mais comum de autenticar APIs sem estado.

Um JWT é apenas uma sequência formada por três partes codificadas em Base64Url e unidas por pontos: header.payload.signature.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0Iiwicm9sZSI6ImFkbWluIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

O cabeçalho

O cabeçalho descreve como o token é assinado. Ele é um pequeno objeto JSON codificado em Base64Url no primeiro segmento.

alg identifica o algoritmo de assinatura (por exemplo, HS256, RS256) e typ é quase sempre JWT.

{
  "alg": "HS256",
  "typ": "JWT"
}

A carga útil

A carga útil contém as declarações — afirmações sobre o usuário e metadados sobre o token. Ela é o segundo segmento.

Importante: a carga útil é apenas codificada, não criptografada. Qualquer pessoa pode decodificá-la; portanto, nunca coloque segredos nela.

{
  "sub": "1234",
  "name": "Alice",
  "role": "admin",
  "exp": 1735689600
}

A assinatura

A assinatura garante que o token não foi adulterado. O servidor a calcula a partir do cabeçalho codificado, da carga útil codificada e de uma chave secreta.

Se alguém alterar um único caractere da carga útil, a assinatura deixará de corresponder e a validação falhará.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secretKey
)

Declarações registradas

Alguns nomes de declarações são padronizados pela especificação JWT (RFC 7519). Eles usam chaves curtas de três letras:

iss — emissor
sub — sujeito (o ID do usuário)
aud — público-alvo
exp — tempo de expiração (segundos Unix)
nbf — não válido antes de
iat — emitido em

{
  "iss": "https://api.myapp.com",
  "aud": "myapp-clients",
  "sub": "42",
  "exp": 1735689600,
  "iat": 1735686000
}

Declarações personalizadas

Além do conjunto registrado, você pode adicionar quaisquer declarações personalizadas de que sua aplicação precise — funções, permissões, IDs de locatários, e-mail e muito mais.

Mantenha a carga útil pequena: cada declaração viaja em todas as requisições.

{
  "sub": "42",
  "email": "alice@myapp.com",
  "role": "admin",
  "tenant_id": "acme",
  "permissions": ["orders:read", "orders:write"]
}

Declarações no ASP.NET Core

No .NET, as declarações são modeladas pelo tipo System.Security.Claims.Claim. Cada declaração é um par de tipo / valor.

Quando um JWT é validado, o ASP.NET Core transforma cada entrada da carga útil em uma Claim no ClaimsPrincipal do usuário.

var claims = new List<Claim>
{
    new Claim(ClaimTypes.NameIdentifier, "42"),
    new Claim(ClaimTypes.Name, "Alice"),
    new Claim(ClaimTypes.Role, "admin"),
    new Claim("tenant_id", "acme")
};

ClaimsPrincipal e ClaimsIdentity

Um usuário autenticado é representado por um ClaimsPrincipal, que contém um ou mais objetos ClaimsIdentity, cada um armazenando um conjunto de declarações.

Em um controlador, você o acessa por meio de User.

// Inside a controller action
var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
bool isAdmin = User.IsInRole("admin");
string? tenant = User.FindFirst("tenant_id")?.Value;

Mapeamento dos tipos de declaração

Por padrão, o manipulador de JWT mapeia chaves curtas de JWT para tipos de declaração longos no formato de URI (por exemplo, sub se torna ClaimTypes.NameIdentifier).

Para manter os nomes curtos originais, desative o mapeamento de entrada uma vez na inicialização.

JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
// Now User.FindFirst("sub") returns the raw 'sub' claim

Por que não usar apenas um cookie de sessão?

Os JWTs são autocontidos: o servidor pode validá-los usando apenas a chave de assinatura, sem consultar o banco de dados nem manter um armazenamento de sessão no servidor.

Isso os torna ideais para APIs dimensionadas horizontalmente e microsserviços, nos quais qualquer nó pode verificar o mesmo token.

// Client sends the token on every request:
// Authorization: Bearer eyJhbGciOiJIUzI1Ni...

A compensação: revogação

Como um JWT é autocontido e confiável até expirar, não é fácil revogar um antes do horário exp.

A mitigação comum é manter os tokens de acesso com curta duração e combiná-los com tokens de atualização (abordados mais adiante neste curso).

// Short-lived access token
exp = iat + 15 * 60;  // 15 minutes

Verificação rápida

Teste sua compreensão da estrutura de um JWT.

Recapitulação

Você aprendeu a anatomia de um JWT e como as declarações funcionam no ASP.NET Core:

Um JWT tem o formato header.payload.signature, e cada parte é codificada em Base64Url.
A carga útil contém declarações registradas e personalizadas, codificadas, mas não criptografadas.
A assinatura garante a integridade usando um segredo ou um par de chaves.
O .NET transforma as declarações em um ClaimsPrincipal, que você lê por meio de User.

Em seguida, você configurará o ASP.NET Core para validar esses tokens.

Perguntas Frequentes

A aula “Estrutura e declarações de JWT” é grátis?

Sim — o texto completo de “Estrutura e declarações de JWT” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de C# Academy, atualize para CoddyKit PRO. O curso de C# Academy inclui 4 aulas no total.

O que vou aprender em “Estrutura e declarações de JWT”?

Entenda o cabeçalho, a carga útil e a assinatura. Você pratica C# Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar C# Academy?

Nenhuma experiência prévia é necessária. C# Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Estrutura e declarações de JWT”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de C# Academy?

Sim. Cada aula de C# Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para C# Academy