JWT explicado: estructura, claims y cómo decodificar uno

Si has trabajado con una API web moderna, te has topado con los JWT — esas largas cadenas de galimatías con dos puntos que aparecen en las respuestas de inicio de sesión y en las cabeceras Authorization. Parecen opacos, pero son sorprendentemente legibles una vez que conoces la estructura. Esta guía explica qué es un JSON Web Token, qué contiene, cómo funciona la firma y los errores de seguridad que hay que evitar.

Para qué sirve un JWT

Un JSON Web Token (JWT) es una forma compacta y autocontenida de llevar un conjunto de claims — afirmaciones como «este es el usuario 42 y se autenticó a las 10:05». Su uso principal es la autenticación: tras iniciar sesión, un servidor emite un JWT, tu app lo devuelve con cada petición y el servidor confía en él en vez de buscarte en un almacén de sesiones cada vez. Como el token lleva la información en sí mismo, se le llama sin estado (stateless).

Las tres partes

Todo JWT son tres secciones codificadas en Base64URL unidas por puntos: header.payload.signature.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.3x9kQ...
└──── header ────┘ └── payload ──┘ └ signature ┘

1. Cabecera (Header)

Metadatos sobre el token — el algoritmo de firma (alg, p. ej. HS256) y el tipo (typ: JWT). Decodificada, es solo un pequeño JSON:

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

2. Carga útil (Payload)

Los claims — los datos reales. Algunos nombres están estandarizados (llamados claims registrados):

• sub — sujeto (subject), normalmente el ID de usuario.
• iss — emisor (issuer), quién creó el token.
• aud — audiencia, para quién es.
• exp — hora de expiración (una marca de tiempo Unix).
• iat — hora de emisión (una marca de tiempo Unix).

Esos valores exp e iat son segundos desde 1970 — si necesitas leerlos como fechas reales, un conversor de marca de tiempo los convierte en horas legibles.

3. Firma (Signature)

La firma es lo que hace fiable al token. El emisor toma la cabecera y la carga útil y, usando una clave secreta, produce una firma criptográfica. Cualquiera con la clave puede verificar que la cabecera y la carga útil no han sido alteradas — cambia un solo carácter en la carga y la firma ya no coincide.

Lo más importante que entender

Un JWT está firmado, no cifrado. La cabecera y la carga útil solo están codificadas en Base64URL, lo que significa que cualquiera puede decodificarlas y leerlas — sin clave. La firma impide la manipulación, no la lectura.

La consecuencia práctica: nunca pongas secretos en la carga útil de un JWT. Ni contraseñas, ni números de tarjeta, ni datos privados — asume que la carga es pública. Puedes confirmarlo tú mismo pegando cualquier token en nuestro decodificador de JWT, que lee la cabecera y los claims al instante, por completo en tu navegador (el token nunca sale de tu dispositivo). Por dentro es solo decodificación Base64 — el decodificador simplemente te ahorra los pasos.

Verificar vs. decodificar

Son dos acciones distintas, y confundirlas es un fallo de seguridad real. Decodificar lee la carga útil — cualquiera puede hacerlo y no prueba nada. Verificar comprueba la firma con la clave y confirma que el token es genuino y no ha sido alterado. Un servidor debe verificar cada token antes de confiar en él; decodificar por sí solo no es autenticación.

Errores comunes

• Confiar en un token sin verificar — comprueba siempre la firma en el servidor antes de actuar según los claims.
• Ignorar la expiración — respeta exp; un token expirado debe rechazarse.
• Guardar datos sensibles en la carga útil — cualquiera puede leerla.
• La trampa `alg: none` — algunas bibliotecas aceptaron alguna vez tokens que afirmaban «sin firma». Recházalos y fija el algoritmo esperado.

Entiende eso y los JWT pasan de ser cadenas intimidantes a un formato simple y transparente: claims legibles, protegidos por una firma que debes verificar antes de confiar.