Cómo decodificar un JWT e inspeccionar sus afirmaciones de forma segura
Respuesta rápida
Un JWT son tres cadenas Base64URL unidas por puntos: header.payload.signature. Decodifica el encabezado y la carga útil con decodificación Base64URL para inspeccionar las afirmaciones, pero la decodificación solo lee los datos, no verifica la autenticidad. Verifique siempre la firma en el servidor antes de confiar en cualquier reclamo. Utilice nuestro decodificador JWT para inspeccionar tokens en su navegador.
Introducción
Un token web JSON (JWT, RFC 7519) es un formato de token compacto y seguro URL que se utiliza para autenticación y autorización. Tiene tres partes codificadas en Base64URL separadas por puntos: header.payload.signature. El encabezado describe el algoritmo, la carga útil incluye afirmaciones (identificación de usuario, roles, vencimiento) y la firma demuestra que el token fue emitido por una parte confiable. Lo más importante es que el encabezado y la carga útil están codificados, no cifrados: cualquiera puede leerlos.
Paso a paso
-
Dividir la ficha en tres partes.
Un JWT se parece a xxxxx.yyyyy.zzzzz. Divida el carácter de punto para obtener el encabezado (parte 0), la carga útil (parte 1) y la firma (parte 2). Si no hay exactamente tres partes, el token está mal formado.
-
Base64URL: decodifica el encabezado
El encabezado es un objeto JSON codificado en Base64URL como {"alg":"HS256","typ":"JWT"}. Base64URL usa - y _ en lugar de + y / y omite el relleno. Decodificalo, luego JSON.parse para leer el algoritmo y escribir. Nuestro decodificador JWT hace esto automáticamente.
-
Base64URL: decodifica la carga útil (reclamaciones)
La carga útil es un JSON objeto de reclamaciones. Los reclamos registrados incluyen iss (emisor), sub (asunto), aud (audiencia), exp (vencimiento), nbf (no antes), iat (emitido en) y jti (identificación del token). Los reclamos privados son específicos de la aplicación (por ejemplo, función, correo electrónico). Decodifica e inspecciona, pero no confíes hasta que esté verificado.
-
Consulta las reclamaciones de caducidad y no anterior
exp y nbf son marcas de tiempo de Unix (segundos). Si la hora actual ya pasó la exp, el token ha caducado y debe rechazarse. Si la hora actual es anterior a nbf, el token aún no es válido. Verifique estos en el lado del cliente para ver la UX, pero aplíquelos en el lado del servidor por motivos de seguridad.
-
Verificar la firma en el servidor (nunca del lado del cliente)
La firma es HMAC-SHA256 (secreta, header.payload) para HS256, o firma RSA/ECDSA para RS256/ES256. La verificación requiere la clave secreta o pública, que nunca debe llegar al navegador. Utilice una biblioteca como jsonwebtoken (Node) o jose para verificar; nunca escriba su propia criptografía.
Ejemplos
Un JWT típico (tres partes)
Aporte: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpmeJf36POk6yJV_adQssw5c
Producción: Header: {"alg":"HS256","typ":"JWT"} Payload: {"sub":"1234567890","name":"John Doe","iat":1516239022}
Carga útil decodificada con reclamos estándar
Aporte: Carga útil de un token de autenticación real
Producción: {"sub":"user-42","iss":"freeonlinetoolsgo.com","exp":1767229200,"iat":1767225600,"role":"admin"}
Detección de token caducado
Aporte: exp: 1609459200 (2021-01-01) verificado el 2026-08-28
Producción: Token is expired —current time (1767225600) > exp (1609459200). Reject and prompt re-login.
Problemas comunes
- Tratar la decodificación como verificación: cualquiera puede crear un JWT con cualquier reclamo y una firma falsa. La decodificación lee la carga útil pero no prueba nada. Verifique siempre la firma con la clave secreta/pública en el servidor antes de confiar en las reclamaciones.
- Usando el algoritmo 'none': la especificación JWT permite alg: none para tokens no seguros. Si su verificador acepta alg: none, un atacante puede falsificar tokens. Configure su biblioteca para que no rechace ninguno y incluya en la lista blanca los algoritmos esperados.
- Almacenamiento de JWT en localStorage: XSS puede leer localStorage y exfiltrar tokens. Prefiera cookies httpOnly, Secure, SameSite=Strict para tokens de sesión o tokens en memoria de corta duración con una cookie de token de actualización.
- No comprobar exp/aud/iss: un token robado es válido hasta que caduque. Siempre verifique exp (vencimiento), aud (público objetivo) e iss (emisor) en cada solicitud para evitar la reproducción del token en todos los servicios.
Consejos
- Utilice tokens de acceso de corta duración (15 minutos) más tokens de actualización de larga duración; esto limita la ventana si se roba un token de acceso.
- Prefiera RS256 (asimétrico) a HS256 (simétrico) cuando varios servicios verifican tokens: cada servicio obtiene la clave pública y solo el emisor tiene la clave privada.
- Utilice nuestro decodificador JWT durante el desarrollo para inspeccionar lo que emite el servidor: muestra el encabezado decodificado, la carga útil y un resumen de reclamo legible por humanos sin enviar el token a ninguna parte.
- Nunca coloque datos confidenciales (contraseñas, PII) en una carga útil JWT; está codificada con Base64, no está cifrada, y cualquiera que intercepte el token puede leer cada reclamo.