Cómo decodificar un token JWT de forma segura (qué contiene)
Un JWT se decodifica, no se descifra, porque sus tres partes están codificadas en Base64URL en lugar de cifradas, lo que significa que cualquiera que tenga el token puede leer su contenido sin ningún secreto ni clave. Un JSON Web Token es simplemente tres cadenas unidas por puntos, header.payload.signature, donde la cabecera y el payload son JSON plano que se ha codificado en Base64URL. Esta guía te muestra exactamente qué hay dentro de un JWT, cómo leer los claims estándar y la diferencia crítica entre decodificar un token (que no necesita nada) y verificarlo (que necesita la clave de firma).
Qué contiene un JWT: cabecera, payload, firma
Un JWT contiene tres segmentos separados por puntos, cada uno codificado en Base64URL: una cabecera, un payload y una firma. Divide un token por sus dos puntos y obtienes exactamente estas tres partes, y las dos primeras se decodifican directamente de vuelta a JSON legible.
La cabecera es un pequeño objeto JSON que nombra el tipo de token y el algoritmo de firma, por ejemplo `{"alg":"HS256","typ":"JWT"}`. El payload es el objeto JSON que transporta los claims, las afirmaciones sobre el usuario o la sesión, como su ID y la caducidad del token. La firma es un hash criptográfico de los dos primeros segmentos más una clave secreta y, a diferencia de las otras, no se decodifica a texto legible.
Como las dos primeras partes solo están codificadas en Base64URL, decodificar un JWT es trivial: invierte la codificación en la cabecera y el payload y verás el JSON en bruto. Esto es intencional, los JWT están pensados para que los lean los sistemas que los reciben.
Decodificar frente a verificar: la diferencia crítica
Decodificar un JWT no requiere ningún secreto, pero verificar uno requiere la clave de firma, y confundir ambas cosas es un error de seguridad grave. Decodificar solo invierte Base64URL para revelar los claims; verificar recalcula la firma con la clave secreta para demostrar que el token es auténtico y no ha sido alterado.
Esto significa que puedes leer cualquier JWT que encuentres, pero leerlo no te dice nada sobre si debes confiar en él. Un atacante puede tomar un token válido, decodificarlo, cambiar el payload para afirmar que es administrador y volver a codificarlo. El token falsificado se decodifica a la perfección; simplemente falla la verificación de la firma, porque el atacante no tiene la clave necesaria para producir una firma coincidente.
La regla para los servidores: nunca tomes una decisión de confianza basándote solo en un payload decodificado. Verifica siempre la firma contra tu clave, y comprueba la caducidad, antes de actuar sobre cualquier claim. Decodificar es para inspección y depuración; la verificación es para autorización.
Por qué los JWT están codificados, no cifrados
Un JWT firmado estándar está codificado, no cifrado, así que su payload es totalmente legible por cualquiera que obtenga el token, razón por la cual nunca debes colocar secretos en su interior. La firma garantiza la integridad, que el contenido no fue manipulado, pero no proporciona ninguna confidencialidad; los claims están en JSON plano y decodificable.
Los desarrolladores cometen habitualmente el error de meter datos sensibles, contraseñas, registros personales completos, identificadores internos, en el payload de un JWT, asumiendo que el token es opaco. No lo es. Cualquiera que intercepte el token, desde el almacenamiento del navegador, un archivo de registro o una captura de red, puede decodificar el payload en segundos.
Mantén los payloads con claims no sensibles: un ID de usuario, roles y campos de tiempo. Si de verdad necesitas ocultar el contenido, eso es una construcción distinta, un JWE (JSON Web Encryption), que sí cifra el payload. Un JWT firmado normal nunca lo hace.
Cómo leer los claims estándar de un JWT
El estándar de JWT, el RFC 7519, define siete nombres de claims registrados que llevan un significado consistente entre sistemas, y todos son opcionales pero muy usados. Reconocerlos te permite leer el payload de cualquier token de un vistazo, sin importar quién lo haya emitido.
Tres de estos claims son marcas de tiempo, exp, iat y nbf, y se almacenan como tiempo Unix: el número de segundos transcurridos desde el 1 de enero de 1970 UTC. Un valor como 1767225600 no es un número aleatorio; es una fecha, y convertirlo revela exactamente cuándo se emitió un token o cuándo caduca. Para hallar la vida útil de un token, resta iat de exp.
La tabla siguiente enumera los siete claims registrados y lo que significa cada uno.
| Claim | Nombre | Significado |
|---|---|---|
| exp | Expiration Time | Marca de tiempo Unix a partir de la cual el token debe rechazarse |
| iat | Issued At | Marca de tiempo Unix de cuándo se creó el token |
| nbf | Not Before | Marca de tiempo Unix antes de la cual el token no debe aceptarse |
| iss | Issuer | Quién emitió el token, a menudo una URL o nombre de servicio |
| sub | Subject | Sobre quién trata el token, normalmente un ID de usuario |
| aud | Audience | Destinatario(s) previsto(s); tu API debería confirmar que figura |
| jti | JWT ID | Un identificador único para este token concreto |
¿Puedo decodificar un JWT sin enviarlo a un servidor?
Sí, un decodificador de JWT del lado del cliente divide y decodifica en Base64URL el token enteramente en tu navegador, así que el token nunca se transmite a ningún servidor. La decodificación es pura manipulación de cadenas que se ejecuta en tu propio dispositivo, no hace falta ninguna petición de red para revelar la cabecera y el payload.
Esto no es solo cómodo, es un control de seguridad real. Un JWT es una credencial al portador: quien lo tenga puede actuar como el usuario hasta que caduque. Pegar un token de producción en un decodificador en línea cualquiera envía esa credencial activa a un tercero desconocido, que podría capturarla y reutilizarla. Una herramienta que decodifica localmente elimina esa exposición por completo, y te permite inspeccionar tokens reales sin entregárselos jamás al servidor de otra persona.
Preguntas frecuentes
¿Puedo decodificar un JWT sin la clave secreta?
Sí. La cabecera y el payload solo están codificados en Base64URL, así que cualquiera puede decodificarlos y leerlos sin ninguna clave. El secreto solo hace falta para verificar o crear la firma, no para leer los claims.
¿Un JWT está cifrado?
Un JWT firmado estándar no está cifrado, solo codificado y firmado. El payload es legible por cualquiera que tenga el token. Usa JWE si de verdad necesitas cifrar el contenido.
¿Cuál es la diferencia entre decodificar y verificar un JWT?
Decodificar revela los claims y no necesita ningún secreto. Verificar recalcula la firma con la clave de firma para confirmar que el token es auténtico y no ha cambiado. Solo se debe confiar en tokens verificados.
¿Qué significan exp e iat en un JWT?
Son los tiempos de caducidad y de emisión, almacenados como marcas de tiempo Unix (segundos desde 1970). Resta iat de exp para obtener la vida útil del token; un token está caducado en cuanto el tiempo actual supera exp.
¿Es seguro pegar un JWT en un decodificador en línea?
Solo si el decodificador se ejecuta enteramente en tu navegador. Un JWT es una credencial al portador activa, y pegar un token de producción en un decodificador del lado del servidor lo envía a un tercero que podría reutilizarlo. Usa una herramienta del lado del cliente.