Estructura y claims de JWT
Comprenda el header, el payload y la signature.
Estructura y claims de JWT es una lección gratuita de C# Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de C# Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de C# Academy incluye 4 lecciones en total.
¿Qué es un JWT?
Un JSON Web Token (JWT) es un formato compacto de token seguro para URL que se utiliza para transmitir de forma segura claims entre dos partes. En ASP.NET Core, es la forma más habitual de autenticar API sin estado.
Un JWT es simplemente una cadena formada por tres partes codificadas en Base64Url y unidas mediante puntos: header.payload.signature.
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0Iiwicm9sZSI6ImFkbWluIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5cEl header
El header describe cómo se firma el token. Es un objeto JSON pequeño que se codifica en Base64Url para formar el primer segmento.
alg indica el algoritmo de firma (por ejemplo, HS256 o RS256) y typ casi siempre es JWT.
{
"alg": "HS256",
"typ": "JWT"
}El payload
El payload contiene los claims: afirmaciones sobre el usuario y metadatos del token. Es el segundo segmento.
Importante: el payload solo está codificado, no cifrado. Cualquiera puede decodificarlo, así que nunca incluya secretos aquí.
{
"sub": "1234",
"name": "Alice",
"role": "admin",
"exp": 1735689600
}La firma
La firma garantiza que el token no ha sido manipulado. El servidor la calcula a partir del header codificado, el payload codificado y una clave secreta.
Si alguien cambia un solo carácter del payload, la firma deja de coincidir y la validación falla.
HMACSHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
secretKey
)Claims registrados
Algunos nombres de claims están estandarizados por la especificación de JWT (RFC 7519). Utilizan claves cortas de tres letras:
iss- emisorsub- sujeto (el id de usuario)aud- audienciaexp- fecha de expiración (segundos Unix)nbf- no válido antes deiat- emitido en
{
"iss": "https://api.myapp.com",
"aud": "myapp-clients",
"sub": "42",
"exp": 1735689600,
"iat": 1735686000
}Claims personalizados
Además del conjunto registrado, puede añadir los claims personalizados que necesite su aplicación: roles, permisos, ids de tenant, correo electrónico y mucho más.
Mantenga pequeño el payload: cada claim viaja en todas las solicitudes.
{
"sub": "42",
"email": "alice@myapp.com",
"role": "admin",
"tenant_id": "acme",
"permissions": ["orders:read", "orders:write"]
}Claims en ASP.NET Core
En .NET, los claims se modelan mediante el tipo System.Security.Claims.Claim. Cada claim es un par de tipo / valor.
Cuando se valida un JWT, ASP.NET Core convierte cada entrada del payload en un Claim dentro del ClaimsPrincipal del usuario.
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 y ClaimsIdentity
Un usuario autenticado se representa mediante un ClaimsPrincipal, que contiene uno o varios objetos ClaimsIdentity, cada uno con un conjunto de claims.
En un controlador, puede acceder a él mediante User.
// Inside a controller action
var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
bool isAdmin = User.IsInRole("admin");
string? tenant = User.FindFirst("tenant_id")?.Value;Mapeo de tipos de claim
De forma predeterminada, el handler de JWT asigna las claves cortas de JWT a tipos de claim largos con formato de URI (por ejemplo, sub se convierte en ClaimTypes.NameIdentifier).
Para conservar los nombres cortos originales, desactive el mapeo de entrada una sola vez durante el arranque.
JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
// Now User.FindFirst("sub") returns the raw 'sub' claim¿Por qué no usar simplemente una cookie de sesión?
Los JWT son autosuficientes: el servidor puede validarlos usando únicamente la clave de firma, sin consultar una base de datos ni almacenar la sesión en el servidor.
Esto los hace ideales para API escaladas horizontalmente y microservicios, donde cualquier nodo puede verificar el mismo token.
// Client sends the token on every request:
// Authorization: Bearer eyJhbGciOiJIUzI1Ni...La contrapartida: la revocación
Como un JWT es autosuficiente y se considera confiable hasta que caduca, no puede revocarlo fácilmente antes de su momento exp.
La mitigación habitual consiste en mantener los access tokens con una duración corta y combinarlos con refresh tokens (que se explican más adelante en este curso).
// Short-lived access token
exp = iat + 15 * 60; // 15 minutesComprobación rápida
Compruebe cuánto entiende de la estructura de los JWT.
Resumen
Ha aprendido la anatomía de un JWT y cómo funcionan los claims en ASP.NET Core:
- Un JWT tiene el formato
header.payload.signature, y cada parte está codificada con Base64Url. - El payload contiene claims registrados y personalizados, codificados pero no cifrados.
- La firma garantiza la integridad mediante un secreto o un par de claves.
- .NET convierte los claims en un
ClaimsPrincipal, al que se accede medianteUser.
A continuación, configurará ASP.NET Core para validar estos tokens.
Preguntas frecuentes
¿La lección «Estructura y claims de JWT» es gratis?
Sí — el texto completo de «Estructura y claims de JWT» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de C# Academy, actualiza a CoddyKit PRO. El curso de C# Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Estructura y claims de JWT»?
Comprenda el header, el payload y la signature. Practicas C# Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar C# Academy?
No se requiere experiencia previa. C# Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.
¿Cuánto tiempo toma la lección «Estructura y claims de JWT»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de C# Academy?
Sí. Cada lección de C# Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Estructura y claims de JWT
- Configuración de la autenticación JWT Bearer
- Emisión de tokens
- Tokens de actualización y caducidad