Introducción: El Token Detrás de Cada Inicio de Sesión
Si has construido o depurado una aplicación web moderna, te has encontrado con el JSON Web Token. Es la pequeña cadena críptica que fluye entre un navegador y una API en casi cada petición autenticada. Cuando los inicios de sesión fallan misteriosamente, cuando las sesiones caducan demasiado pronto o nunca caducan, o cuando un servicio rechaza el token de otro, un JWT suele estar en el centro. Esta guía explica qué es un JWT, cómo encajan sus piezas y cómo depurar los problemas que causan — con un compañero práctico en nuestro Decodificador JWT, que decodifica y verifica tokens por completo en tu navegador.
Firmado, No Cifrado: El Modelo Mental Clave
El malentendido más común sobre los JWT es que ocultan su contenido. No lo hacen. Un JWT estándar está firmado, no cifrado. Cualquiera que tenga el token puede leer todo lo que hay dentro. La firma no oculta los datos; demuestra dos cosas: que el contenido no se ha alterado y que lo emitió alguien que posee la clave de firma.
Por eso un decodificador puede mostrarte el contenido de cualquier token sin una contraseña, y por eso nunca debes poner secretos — contraseñas, claves de API, datos privados — dentro del payload de un JWT. Si se requiere confidencialidad, el token debe cifrarse (el estándar JWE) o enviarse solo por canales seguros. Trata el payload como información pública que resulta ser a prueba de manipulaciones.
Las Tres Partes de un JWT
Un JWT son tres segmentos codificados en base64url separados por puntos: header.payload.signature. Pega cualquier token en el decodificador y verás iluminarse estas tres partes.
La Cabecera
La cabecera es un pequeño objeto JSON que describe el token. Su campo más importante es alg, el algoritmo usado para firmarlo — HS256, RS256, ES256, etc. Suele llevar también typ ("JWT") y puede incluir kid, un identificador de clave que indica al verificador qué clave firmó este token concreto, lo que importa cuando un servicio rota claves.
El Payload
El payload contiene los claims — las afirmaciones que hace el token. Algunos son claims registrados estándar con significados definidos; otros son claims personalizados que tu aplicación añade, como el rol de un usuario, su tenant o sus scopes permitidos. Como el payload es legible, es lo primero que miras al depurar "este usuario debería tener acceso pero no lo tiene".
La Firma
La firma se calcula sobre la cabecera y el payload usando el algoritmo indicado en la cabecera. Es la parte que hace fiable a un token. Cambia un solo carácter del payload y la firma deja de coincidir, así que un servidor verificador rechazará el token.
Claims Estándar Que Verás Constantemente
iss(issuer) — quién creó y firmó el token, a menudo la URL de un proveedor de identidad.sub(subject) — el principal que representa el token, normalmente un id de usuario estable.aud(audience) — el destinatario previsto. Un token acuñado para una API debería ser rechazado por otra; las audiencias no coincidentes son una causa frecuente de fallos de auth entre servicios.exp(expiration) — una marca de tiempo Unix tras la cual el token debe rechazarse.nbf(not before) — una marca de tiempo antes de la cual el token aún no es válido.iat(issued at) — cuándo se creó el token.jti(JWT id) — un id único, útil para listas de revocación.
El decodificador convierte los claims de marca de tiempo en fechas legibles y muestra si el token es válido ahora mismo, lo que convierte el error de autenticación más común — un token caducado o aún no válido, a menudo causado por desfase del reloj del servidor — en un diagnóstico de un vistazo.
Cómo Funciona Realmente la Verificación
La verificación recalcula la firma y la compara. Con un algoritmo simétrico como HS256, el mismo secreto firma y verifica usando un HMAC. Tanto el emisor como el verificador deben compartir ese secreto, lo que funciona bien dentro de un único límite de confianza pero no escala entre organizaciones. Con un algoritmo asimétrico como RS256 o ES256, una clave privada firma y la clave pública correspondiente verifica. Esto es lo que permite a los proveedores de identidad publicar una clave pública — a menudo en un endpoint JWKS — para que cualquier servicio valide tokens sin poder falsificarlos. En el Decodificador JWT, pegas el secreto HMAC o la clave pública PEM y la Web Crypto API del navegador hace la comprobación localmente; tu clave nunca sale de la página.
Depurar los Problemas de JWT Más Comunes
"El token se rechaza de inmediato." Comprueba primero el algoritmo y la firma. Un desajuste entre el algoritmo que usó el emisor y el que espera el verificador, o un secreto/clave equivocado, hará fallar la verificación. Decodifica la cabecera para confirmar alg.
"Funciona y de repente deja de funcionar." Mira exp. El token ha caducado. Decodifícalo y lee la fecha de caducidad; si está en el pasado, el cliente necesita renovar. Si los tokens caducan mucho antes de lo esperado, la configuración de vida del emisor probablemente es demasiado corta.
"Falla solo en un servidor." Compara aud con lo que ese servidor espera, y comprueba el desfase de reloj que afecta a nbf/exp. Un servidor cuyo reloj va unos minutos desviado puede rechazar tokens por lo demás válidos.
"El payload parece correcto pero se deniega el acceso." Verifica la firma. Un payload de aspecto correcto no significa nada si el token no está firmado o está firmado con la clave equivocada. Decodificar muestra los claims; solo la verificación prueba que son fiables.
Errores de Seguridad Que Todo Desarrollador Debe Conocer
- Nunca te fíes de un payload decodificado. Verifica siempre la firma en el servidor antes de actuar sobre cualquier claim.
- Rechaza "alg: none". Fija el algoritmo esperado; nunca dejes que la propia cabecera del token decida si hay verificación.
- Mantén los tokens de vida corta. Una caducidad larga convierte un token filtrado en una credencial de larga vida. Usa tokens de refresco para la longevidad, no enormes tiempos de vida de los tokens de acceso.
- No pongas secretos en el payload. Es legible por cualquiera que tenga el token.
- Nunca pegues tokens activos en herramientas online del lado del servidor. Eso transmite tu credencial de sesión a un tercero. Usa un decodificador del lado del cliente que procese todo localmente.
Tokens de Acceso, Tokens de Refresco y Diseño de Sesiones
Los sistemas en producción rara vez usan un solo token. Usan dos, y entender la división evita una clase de errores de seguridad. El token de acceso es el JWT de vida corta enviado en cada petición a la API. Debería caducar en minutos, para que si se intercepta sea útil solo brevemente. El token de refresco es una credencial de vida más larga y mejor protegida, normalmente guardada en una cookie httpOnly, que se intercambia en el servidor de autenticación por un nuevo token de acceso cuando el actual caduca.
El error a evitar es ampliar la vida del token de acceso a días para que los usuarios no tengan que iniciar sesión a menudo. Eso convierte un token de acceso filtrado en una credencial de larga vida que un atacante puede reproducir. La respuesta correcta es una caducidad corta del token de acceso más un token de refresco, lo que da comodidad y seguridad. Cuando decodificas un token aquí y ves un exp a solo unos minutos, eso suele ser el sistema funcionando como se diseñó, no un fallo — y leer la caducidad es la forma más rápida de confirmar que tus tiempos de vida coinciden con tu política de seguridad.
También explica una confusión común: un usuario informa de que se le "cierra la sesión" demasiado pronto, pero que el token de acceso caduque es lo esperado; la pregunta real es si el refresco silencioso funciona. Decodificar ambos tokens — el token de acceso que caduca y el token de refresco de vida más larga — muestra rápidamente qué mitad del flujo se comporta mal.
Dónde Encajan los JWT y Dónde No
Los JWT brillan para la autenticación sin estado entre servicios: un verificador con la clave correcta puede validar un token sin consultar una base de datos, lo que escala de maravilla. Son menos ideales cuando necesitas revocación instantánea, porque un token firmado sigue siendo válido hasta que caduca aunque quieras cancelarlo antes. Los equipos lo resuelven con vidas cortas, listas de bloqueo de tokens basadas en jti, o un híbrido de verificación sin estado más una comprobación rápida de revocación. Conocer este compromiso ayuda a decidir cuándo un JWT es la herramienta adecuada y cuándo una sesión tradicional del lado del servidor es más simple. El decodificador ayuda en ambos casos al hacer visibles de un vistazo los claims y la vida del token.
Un Flujo Práctico de Depuración
- Pega el token que falla en el Decodificador JWT y lee las insignias de algoritmo y estado.
- Comprueba las fechas de caducidad y not-before frente a la hora actual.
- Compara
issyaudcon lo que espera el servicio que rechaza. - Si la estructura parece correcta, pega el secreto o la clave pública y verifica la firma.
- Si la verificación falla, el problema es la clave, el algoritmo o un token manipulado; si pasa, el problema es un desajuste de claims o una política del lado del servidor.
Conclusión
Los JSON Web Tokens son simples una vez que encaja el modelo mental: tres segmentos legibles y firmados que llevan claims, fiables solo después de que la firma se verifique. La mayoría de los errores de autenticación se reducen a caducidad, audiencia, algoritmo o un paso de verificación que falta — todo lo cual puedes diagnosticar en segundos decodificando el token y comprobando sus claims. Ten a mano el Decodificador JWT para exactamente eso, y combínalo con nuestro Formateador JSON cuando necesites leer un payload denso. Todo permanece en tu navegador, así que incluso los tokens de producción nunca salen de tu máquina.