Cómo funcionan los JSON Web Tokens (JWT)

Un JSON Web Token (JWT, se pronuncia «yot») es una cadena compacta y firmada que lleva unos pocos datos, llamados claims, de una parte a otra. Los servidores los entregan tras iniciar sesión y su aplicación devuelve el token con cada petición para demostrar quién es, sin que el servidor mantenga una sesión. Decodifique cualquier token con el Decodificador de JWT o cree uno con el Generador y Verificador de JWT.

Tres partes separadas por puntos

Un JWT tiene el aspecto cabecera.carga.firma. Cada parte es Base64 en su forma segura para URL. Este es un token real creado con el secreto secret:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFuYSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoxNzAwMDAzNjAwfQ.K5CXsF2jBQ9-Pr4xg7yeVj3Vr-Be0jvTHInQnYK-aSk

La cabecera (eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9) se decodifica como:

{"alg":"HS256","typ":"JWT"}

La carga (eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFuYSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoxNzAwMDAzNjAwfQ) se decodifica como:

{"sub":"1234567890","name":"Ana","iat":1700000000,"exp":1700003600}

La firma (K5CXsF2jBQ9-Pr4xg7yeVj3Vr-Be0jvTHInQnYK-aSk) se calcula sobre las dos primeras partes con el algoritmo y la clave que indica la cabecera. HS256 es HMAC con SHA-256: quien conoce el secreto puede tanto crearla como comprobarla.

Claims registrados

Los tiempos están en segundos desde 1970 (vea el Conversor de Timestamp Unix): el token anterior se emitió en 1700000000, el 14 de noviembre de 2023, y caduca una hora después.

Cómo comprueba un servidor un token

1. Divide el token en sus tres partes y decodifica la cabecera.
2. Recalcula la firma sobre cabecera.carga con el algoritmo y la clave esperados y la compara con la del token. Con otro secreto falla: el token anterior se verifica con secret y se rechaza con cualquier otro.
3. Comprueba los claims: exp no ha pasado, nbf sí, y iss y aud tienen los valores esperados.

Algoritmos de firma

• HS256 / HS384 / HS512 usan un único secreto compartido. Es sencillo, pero todo servicio que verifica tokens también puede falsificarlos.
• RS256 / ES256 usan una clave privada para firmar y una pública para verificar, así que la pública puede compartirse ampliamente. Prefiéralos cuando muchos servicios verifican tokens emitidos por uno solo.

Trampas habituales

• Un JWT está firmado, no cifrado. Cualquiera puede leer la carga decodificándola. No ponga nunca contraseñas ni secretos en ella.
• Fije siempre el algoritmo en el servidor. Acepte solo el algoritmo que espera. Fiarse del campo alg ha provocado ataques, como la cabecera {"alg": "none"} que algunas bibliotecas aceptaron en su día como «no requiere firma».
• Use un exp corto. Un token robado funciona hasta que caduca. Use duraciones cortas más tokens de refresco.
• Un token no se puede revocar por sí mismo. Una vez emitido es válido hasta exp. Si necesita cierre de sesión instantáneo, mantenga una lista de denegación de valores jti o use sesiones en el servidor.
• Guarde los tokens con cuidado. Los tokens en localStorage son legibles por cualquier script de la página, así que un fallo XSS los expone; una cookie HttpOnly es más difícil de robar.
• Use un secreto largo y aleatorio para HMAC, no una palabra como secret. El ejemplo de aquí es solo demostrativo.

Vea JWT y HMAC.