Cómo decodificar e inspeccionar tokens JWT
Los tokens JSON Web Token (JWT) son la forma más habitual de gestionar la autenticación en las aplicaciones web modernas. Cuando algo falla en la autenticación — un usuario se desconecta sin razón, los permisos son incorrectos o una API devuelve 401 —, decodificar el JWT suele ser el primer paso de depuración.
Lo que contiene un JWT
Un JWT tiene tres partes separadas por puntos:
eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UEncabezado — contiene el algoritmo (HS256, RS256, etc.) y el tipo de token.
{"alg": "HS256", "typ": "JWT"}Carga útil — contiene reclamaciones (afirmaciones) sobre el usuario y el token.
{"sub": "1234567890", "name": "Alice", "exp": 1700000000}Firma — una huella criptográfica que garantiza que el token no se ha alterado. No puedes leerla sin la clave de firma.
Reclamaciones JWT habituales
| Reclamación | Nombre completo | Contenido |
|---|---|---|
sub |
Subject | ID o identificador de usuario |
exp |
Expiration | Marca de tiempo Unix de fin de validez |
iat |
Issued At | Marca de tiempo Unix de creación |
iss |
Issuer | Quién creó el token (tu servidor de autenticación) |
aud |
Audience | A quién está destinado el token |
nbf |
Not Before | El token no es válido antes de esta fecha |
jti |
JWT ID | Identificador único del token |
Cómo decodificar un JWT
- Pega tu token — introduce el JWT completo (formato encabezado.carga.firma) en el decodificador.
- Consulta las secciones decodificadas — la herramienta muestra el encabezado (algoritmo), la carga útil (reclamaciones) y la firma en forma de JSON formateado.
- Verifica las reclamaciones — examina la fecha de expiración, el emisor, el sujeto y cualquier reclamación personalizada.
Depurar con JWT
¿Token expirado? Comprueba la reclamación exp. Convierte la marca de tiempo Unix en una fecha legible. Si está pasada, el token ha expirado y hay que renovarlo.
¿Permisos incorrectos? Busca reclamaciones de rol o de alcance en la carga útil. Varían según las implementaciones, pero suelen parecerse a "role": "admin" o "scope": "read write".
¿Problema de identidad de usuario? La reclamación sub identifica al usuario. Comprueba que corresponde al ID esperado.
¿Token rechazado? Verifica la reclamación aud (audiencia). Si la API espera una audiencia específica y el token tiene otra, será rechazado.
Notas de seguridad importantes
- Los JWT no están cifrados — cualquiera puede decodificar la carga útil. No pongas contraseñas, claves de API u otros secretos en un JWT.
- Verifica siempre las firmas en el servidor — un decodificador te muestra lo que el token afirma, pero solo la verificación de firma prueba que no se ha alterado.
- Comprueba la expiración — los tokens expirados deben rechazarse siempre. Si tu aplicación acepta tokens expirados, es un fallo de seguridad.
Preguntas frecuentes
¿Puedo verificar una firma JWT con un decodificador?
No. La verificación de firma requiere el secreto de firma o la clave pública, que se guardan en tu servidor. Un decodificador te muestra lo que hay en el token, pero la verificación criptográfica debe hacerse en tu backend. Nunca confíes en un JWT no verificado en producción.
¿Es seguro pegar un JWT en una herramienta en línea?
Sí, cuando la herramienta se ejecuta en tu navegador. Los decodificadores en el navegador procesan el token localmente — nada se envía a un servidor. Evita las herramientas que hacen peticiones de red con tu token.
¿Qué es la reclamación exp?
La reclamación exp (expiration) es una marca de tiempo Unix que indica cuándo expira el token. Tras esa fecha, el token debe rechazarse. Comprueba siempre esta reclamación para depurar problemas de autenticación.
¿Pueden cifrarse los JWT?
Los JWT estándar (JWS) están firmados pero no cifrados — cualquiera puede decodificar la carga útil. Los tokens JWE (JSON Web Encryption) están cifrados, pero son menos habituales. Nunca pongas datos sensibles (contraseñas, secretos) en una carga útil JWT estándar.