Decodificación de Token JWT: Ver Header, Payload y Claims

Header Decodificado

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

Payload Decodificado

{
  "sub": "1234567890",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1735689600
}

Firma

TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

La firma no se puede decodificar. No son datos codificados, sino la salida de una operación HMAC-SHA256. Para verificarla, necesitas la clave secreta utilizada al emitir el token.

Estructura JWT de Tres Partes

Un JWT son tres secciones codificadas en Base64url unidas por puntos:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0
.
TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

La estructura está definida por RFC 7519 y RFC 7515. Cada sección tiene un proposito diferente:

Header

El header específica el tipo de token y el algoritmo de firma. alg le dice al validador que algoritmo se uso para calcular la firma. typ es siempre JWT para tokens estándar. Algunos tokens también incluyen kid (key ID) para indicar que clave se uso; esto importa cuando un servidor de autorización rota las claves.

Payload

El payload contiene los claims: declaraciones sobre el sujeto y metadatos adicionales. Los claims registrados estándar tienen nombres cortos para mantener los tokens compactos (sub, iss, exp). Los claims personalizados pueden ser cualquier cosa que tu aplicación necesite, pero la especificación JWT recomienda usar un formato con espacio de nombres para claims personalizados para evitar colisiones (por ejemplo, https://myapp.com/role).

Firma

La firma se calcula sobre base64url(header) + "." + base64url(payload) usando el algoritmo especificado en el header. Para HS256 es HMAC-SHA256(secret, data). Para RS256 es RSA-SHA256(privateKey, data). El validador recalcula la firma a partir del header y payload recibidos y la compara con la tercera sección. Si no coinciden, el token ha sido manipulado.

Codificación Base64url

Los JWT usan Base64url, una variante de Base64 segura para URL. Usa - en lugar de + y _ en lugar de /, y omite los caracteres de relleno =. Esto hace que los tokens JWT se puedan incluir en parámetros de consulta URL y encabezados HTTP sin necesidad de codificación porcentual.

Base64 estándar requiere caracteres de relleno = y puede contener + o / que tienen significado especial en las URL. Base64url evita todo esto usando caracteres que no necesitan escaparse en las URL.

Para decodificar manualmente la sección del payload:

# Sección del payload (la parte media entre los dos puntos)
PAYLOAD="eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0"

# Agregar relleno y decodificar (macOS/Linux)
python3 -c "
import base64, json, sys
s = sys.argv[1]
pad = s + '=' * (4 - len(s) % 4)
decoded = base64.urlsafe_b64decode(pad)
print(json.dumps(json.loads(decoded), indent=2))
" "$PAYLOAD"

Explicación de Claims Estándar

No todos los claims son obligatorios. exp y sub son los más utilizados. El claim aud es importante para servicios que comparten el mismo servidor de autorización. Sin el, un token destinado al servicio A podría usarse contra el servicio B.

Decodificar No Es Confiar

Esto es lo más importante que entender sobre los decodificadores JWT. Decodificar un token revela sus claims. No dice si esos claims son correctos ni si el token es legitimo.

Un atacante puede crear cualquier JWT a mano. Sin verificación de firma, no hay forma de distinguir un token real de uno falso. Esto importa porque:

1. Ataque alg: none. Algunas bibliotecas JWT antiguas aceptaban como válidos tokens con "alg": "none" en el header y sin firma. Nunca aceptes tokens sin firmar.

2. Ataques de confusión de algoritmo. Si tu servidor usa RS256 (asimetrico), un atacante puede enviar un token con "alg": "HS256" usando tu clave pública como clave secreta HMAC. Las bibliotecas con implementación debil de algoritmos lo verificarian exitosamente. Siempre específica explicitamente el algoritmo esperado.

3. Tokens expirados. Decodificar revela el claim exp, pero aún necesitas verificar si la hora actual lo ha superado.

En producción, usa una biblioteca JWT bien mantenida que maneje la verificación, fijación de algoritmos y control de expiración. Nunca implementes la verificación JWT tu mismo.

Donde se Usan los JWT

OAuth 2.0 / OpenID Connect

Los access tokens e ID tokens en flujos OAuth son frecuentemente JWT. El ID token en OIDC es siempre un JWT. Los access tokens pueden ser JWT o no, dependiendo del servidor de autorización.

Autenticación de API

Un servidor emite un JWT cuando un usuario inicia sesión. El cliente lo envía en solicitudes posteriores en el encabezado Authorization: Bearer <token>. El servidor verifica la firma y lee los claims para identificar al usuario y verificar permisos.

Datos de sesión sin estado

Algunas aplicaciones codifican el estado de sesión (ID de usuario, rol, preferencias) en el payload JWT para evitar una consulta a la base de datos en cada solicitud. El intercambio: los tokens no pueden revocarse antes de la expiración sin infraestructura adicional (una lista negra o expiración corta + refresh tokens).

Autenticación de servicio a servicio

Los microservicios internos suelen usar JWT para autenticar llamadas entre si, con tiempos de expiración cortos (minutos en lugar de horas).

Depurar Problemas de JWT

Cuándo falla una solicitud autenticada con JWT, un decodificador es la primera herramienta a usar:

• El token ha expirado? Compara el valor exp con la hora Unix actual.
• La audiencia es correcta? Verifica que aud coincida con lo que espera tu servicio.
• El emisor es correcto? Verifica que iss coincida con la URL de tu servidor de autorización.
• Los claims personalizados están presentes? Si tu aplicación espera un claim role o permissions, verifica que esten en el payload.
• El algoritmo es correcto? Verifica que alg en el header coincida con lo que espera tu código de verificación.

Los errores de firma requieren la clave secreta o pública real para diagnosticarlos. Un decodificador no puede decirte por qué una firma es incorrecta, solo que algoritmo se uso para crearla.