Qué es un JWT
Un JSON Web Token (JWT, que se pronuncia «yot») es una cadena compacta que lleva información —casi siempre quién es un usuario y qué puede hacer— y que está firmada, de modo que quien la recibe puede comprobar que no fue alterada. Está definido en el RFC 7519 y es la base de buena parte de la autenticación moderna: sesiones sin estado en las API, inicio de sesión con OAuth 2.0 y OpenID Connect, y comunicación entre servicios.
Un JWT firmado (técnicamente, un JWS) tiene tres partes en Base64URL, separadas por puntos: encabezado.contenido.firma. Existe también una variante cifrada (JWE) con cinco partes, cuyo contenido no se puede leer sin la clave; esta herramienta muestra su encabezado y lo indica.
Cómo usar el decodificador
- Pegue el token en el cuadro. Funciona con el prefijo
Bearer, con comillas o con saltos de línea, que se ignoran. - Vea el encabezado, el contenido y la tabla de reclamaciones. Las fechas
exp,iat,nbfyauth_timese convierten a fecha legible, con el tiempo que falta o que ha pasado. - Revise el estado (vigente, expirado…) y los avisos de seguridad, si los hay.
- Para comprobar la firma, abra «Verificar la firma» y escriba la clave secreta (HS256) o la clave pública (RS256, ES256…). No se verifica nada sin una clave.
Los botones Ejemplo caducado y Ejemplo vigente crean en su navegador un token firmado con HS256 y la clave karven-secreto, para que pueda probar la verificación y los distintos estados.
Las tres partes del token
Este es el token de ejemplo más conocido, decodificado con la herramienta:
| Parte | Contenido decodificado | Para qué sirve |
|---|---|---|
| Encabezado (header) | {"alg":"HS256","typ":"JWT"} | Indica el algoritmo de la firma (alg), el tipo de token (typ) y, a menudo, el identificador de la clave (kid). |
| Contenido (payload) | {"sub":"1234567890","name":"John Doe","iat":1516239022} | Las reclamaciones (claims): los datos que transporta el token. |
| Firma (signature) | 32 bytes | Se calcula con el encabezado, el contenido y una clave. Permite detectar cualquier modificación. |
Las reclamaciones registradas por el estándar son las siguientes; cualquier otra es «pública» (acordada, como las de OpenID Connect) o «privada» (propia de cada sistema):
| Reclamación | Significado |
|---|---|
iss | Emisor (issuer): quién creó y firmó el token |
sub | Sujeto (subject): a quién identifica; suele ser el identificador del usuario |
aud | Audiencia (audience): para quién se emitió; el receptor debe comprobar que es él |
exp | Caducidad (expiration time): a partir de esa fecha el token ya no es válido |
nbf | No válido antes de (not before): el token no se acepta hasta esa fecha |
iat | Emitido en (issued at): cuándo se creó el token |
jti | Identificador único del token (JWT ID); sirve para revocarlo o evitar repeticiones |
Decodificar no requiere ninguna clave
Esta herramienta lee el contenido de un token sin conocer ningún secreto, y eso es así por diseño: Base64URL es una codificación, no un cifrado. Cualquiera que tenga el token puede ver lo que lleva dentro. La firma solo garantiza que no se ha modificado, no que sea confidencial.
Consecuencia práctica. No ponga contraseñas, claves de API, números de tarjeta ni datos personales sensibles en el contenido de un JWT firmado. Si necesita que el contenido sea secreto, use un JWE (cifrado) o, mejor aún, guarde los datos en el servidor y deje en el token solo un identificador.
Cómo se firma un token y qué demuestra verificarla
El emisor calcula la firma con una clave sobre encabezado.contenido, y el receptor repite la comprobación. Hay dos familias de algoritmos:
| Algoritmo | Tipo | Claves | Cuándo se usa |
|---|---|---|---|
| HS256, HS384, HS512 | Simétrico (HMAC) | La misma clave secreta firma y verifica. | Sistemas donde el emisor y el verificador son el mismo servicio. Sencillo, pero quien verifica también podría fabricar tokens. |
| RS256, RS384, RS512 | Asimétrico (RSA PKCS#1 v1.5) | La clave privada firma; la pública verifica. | Proveedores de identidad (OAuth y OpenID Connect), que publican sus claves públicas. El más extendido. |
| PS256, PS384, PS512 | Asimétrico (RSA-PSS) | Privada firma, pública verifica. | La variante moderna de RSA, exigida por algunos perfiles de seguridad financiera (FAPI). |
| ES256, ES384, ES512 | Asimétrico (ECDSA) | Privada firma, pública verifica. | Firmas y claves más cortas. Habitual en tokens móviles y en proveedores modernos. |
| EdDSA | Asimétrico (Ed25519) | Privada firma, pública verifica. | Moderno y rápido. Esta herramienta lo reconoce, pero no puede verificarlo. |
| none | Sin firma | — | Nunca debe aceptarse en producción. |
Una firma válida demuestra que el token lo emitió quien posee la clave y que no se modificó. No demuestra que los datos sean ciertos, que el usuario siga existiendo ni que el token no haya sido revocado: para eso hay que comprobar además las fechas, el emisor, la audiencia y, si hace falta, una lista de revocación.
Las fechas de un JWT
Las reclamaciones de tiempo (exp, nbf, iat) son números de segundos desde el 1 de enero de 1970 UTC (tiempo Unix), no milisegundos. Un exp con 13 cifras es casi siempre un error de quien generó el token. La herramienta las convierte automáticamente; para convertir otros valores use el conversor de timestamp. En la práctica, los servidores aceptan un pequeño margen (de 30 a 60 segundos) para compensar relojes ligeramente desajustados entre el emisor y el receptor.
Errores de seguridad frecuentes
- Aceptar
alg: none. Algunas bibliotecas antiguas daban por bueno un token sin firma si su encabezado lo pedía. El servidor debe fijar los algoritmos permitidos y no fiarse del que declara el token. - Confusión de algoritmos. Si un servidor que espera RS256 toma el algoritmo del encabezado y un atacante lo cambia a HS256, podría firmar el token usando como secreto la clave pública, que es conocida. Solución: fijar el algoritmo esperado para cada clave.
- Fiarse de
jku,jwk,x5uokid. Si el servidor descarga o busca la clave según lo que diga el propio token, un atacante puede indicar la suya. La clave debe venir siempre de una fuente de confianza. - No comprobar
exp,issyaud. Validar la firma no basta: hay que verificar que el token no caducó, que lo emitió quien se espera y que está destinado a este servicio. - Tokens de larga duración. Un JWT no se puede revocar fácilmente antes de que caduque. Use tokens de acceso de vida corta (minutos) con tokens de refresco que se puedan revocar.
- Guardarlos donde el JavaScript pueda leerlos. En
localStorage, un ataque XSS puede robarlos. Las cookiesHttpOnly,SecureySameSitereducen ese riesgo (con protección contra CSRF). - Registrar los tokens en los logs o pegarlos en sitios que no controla: un token vigente es una credencial.
Por qué un token no se decodifica
| Mensaje o síntoma | Causa habitual | Qué hacer |
|---|---|---|
| «Tiene N partes» | Se copió el token incompleto, o es otro tipo de valor (una clave de API, un identificador de sesión). | Un JWT tiene tres partes separadas por dos puntos. Cópielo entero. |
| «El carácter … no puede aparecer» | Se copiaron comillas, una coma, un espacio o texto de alrededor. | Copie solo el token. Las comillas, los espacios y «Bearer » se ignoran, pero otros símbolos no. |
| «No es Base64URL válido» | El token se cortó, o se alteró al pasar por un correo o un chat. | Vuelva a obtener el token. Si tiene saltos de línea, la herramienta los quita. |
| «No es JSON válido» | La parte decodificada no es un objeto JSON (o el token está dañado). | Compruebe el contenido decodificado con el validador JSON. |
| El token se ve bien pero la firma «no es válida» | La clave no es la correcta, el algoritmo no corresponde, o la clave secreta estaba en Base64 y no se marcó la casilla. | Compruebe la clave y el algoritmo del encabezado. Para las claves públicas use PEM «BEGIN PUBLIC KEY» o JWK. |
Las tres partes de un JWT se codifican en Base64URL, la variante de Base64 apta para URL; puede explorar esa codificación con la herramienta de Base64.
Preguntas frecuentes
¿Se envía mi token a algún servidor?
No. La decodificación y la verificación de la firma se hacen en su navegador con JavaScript y la API criptográfica del propio navegador; el token y la clave no salen de su equipo. Aun así, trate los tokens vigentes como contraseñas y evite pegarlos en sitios que no controla.
¿Por qué se puede leer un JWT sin ninguna clave?
Porque el encabezado y el contenido solo están codificados en Base64URL, no cifrados. La clave se usa para la firma, que sirve para detectar modificaciones, no para ocultar los datos. Por eso no deben ir secretos en el contenido de un JWT firmado.
¿Cómo sé si un token ha caducado?
Mire la reclamación exp: son los segundos desde 1970 en que deja de ser válido. La herramienta la convierte a fecha y le indica si el token está expirado, vigente o sin caducidad (lo que se considera un riesgo).
¿Qué diferencia hay entre HS256 y RS256?
HS256 usa una única clave secreta compartida para firmar y verificar; RS256 usa un par de claves: la privada firma y la pública verifica. Con RS256, quien verifica no puede fabricar tokens, por eso lo usan los proveedores de identidad.
¿Qué claves admite la verificación?
Para HS256, HS384 y HS512, la clave secreta como texto (o en Base64). Para RS, PS y ES, la clave pública en formato PEM (BEGIN PUBLIC KEY) o JWK, incluido un conjunto JWKS, del que se elige la clave por su kid. Las claves privadas se rechazan a propósito.
¿Que la firma sea válida significa que puedo fiarme del token?
Significa que lo firmó quien tiene la clave y que no se modificó. Además debe comprobar que no ha caducado, que el emisor (iss) y la audiencia (aud) son los esperados y, si procede, que no ha sido revocado.