¿Qué es un JWT? Estructura, firma y uso seguro
Tres fragmentos base64url separados por puntos: un encabezado, un payload y una firma. Aprende qué demuestra cada parte, qué no demuestra y los cinco errores que convierten un JWT en un agujero de seguridad.
Qué aprenderás
- Leer un JWT y nombrar sus tres partes
- Explicar qué demuestra la firma, y qué no demuestra
- Usar los claims estándar (exp, iss, aud, sub) correctamente
- Decidir cuándo un JWT supera a una sesión del lado del servidor (y cuándo pierde)
- Evitar los cinco errores clásicos de seguridad de JWT
- Qué es un JWT
- Anatomía: las tres partes
- Cómo funcionan la firma y la verificación
- Los claims estándar
- Cuándo usar un JWT, y cuándo no
- Errores comunes
- Pruébalo: decodificador JWT
- Preguntas frecuentes
Qué es un JWT
A JSON Web Token (JWT) es una forma compacta y segura para URL de pasar un claim firmado entre dos partes. Tiene este aspecto:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlZhbGV2IiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Tres bloques separados por puntos: header.payload.signature. Un servidor crea uno después de iniciar sesión, te lo entrega y tú lo devuelves con cada petición, normalmente en una cabecera Authorization: Bearer <token> cabecera. El servidor verifica la firma y confía en los claims que contiene, sin buscar nada en una base de datos. Esa propiedad de «sin búsqueda» es todo el sentido, y, como veremos, también la principal debilidad.
Anatomía: las tres partes
Cada parte es JSON codificado en base64url (base64 con +// sustituido por -/_ y sin relleno, para que sobreviva en una URL). Decodifica el ejemplo anterior y obtendrás:
// Header — how the token is signed
{ "alg": "HS256", "typ": "JWT" }
// Payload — the claims (statements about the user)
{ "sub": "1234567890", "name": "Valev", "admin": true, "iat": 1516239022 }
// Signature — HMAC-SHA256 over header.payload, with a secret key| Parte | Contenido | ¿Secreto? |
|---|---|---|
| Encabezado | Algoritmo de firma (alg) y tipo (typ) | No: cualquiera puede leerlo |
| Payload | Claims: quién eres, qué puedes hacer, cuándo caduca | No: cualquiera puede leerlo |
| Firma | Hash del encabezado + payload, con clave secreta | Sí: solo el emisor puede crearla |
Cómo funcionan la firma y la verificación
Para crear la firma, el emisor toma base64url(header) + "." + base64url(payload) y lo firma:
HMAC-SHA256(secret, header + "." + payload) // HS256: shared secret RS256: sign with a private key, verify with a public key
La verificación es el mismo cálculo a la inversa: el servidor vuelve a calcular la firma sobre el encabezado y el payload recibidos, usando su propia clave secreta, y compara. Si cambia aunque sea un carácter del payload — por ejemplo, cambiar "admin": false a true — la firma ya no coincide y el token se rechaza.
Importan dos familias de algoritmos. Simétrico (HS256): un secreto compartido firma y verifica; sencillo, pero cualquiera con el secreto puede falsificar tokens, así que solo el emisor puede tenerlo. Asimétrico (RS256/ES256): una clave privada firma y una clave pública verifica; el verificador puede ser un servicio distinto, y así funciona la federación del estilo «iniciar sesión con Google».
Los claims estándar
| Claim | Significado | Por qué importa |
|---|---|---|
iss | Emisor: quién creó el token | Rechaza tokens de desconocidos |
sub | Sujeto: de quién es este token (ID de usuario) | La identidad con la que actúa la app |
aud | Audiencia: para qué servicio es el token | Evita que un token de una app se reutilice en otra |
exp | Caducidad: momento Unix a partir del cual no es válido | Limita el daño de un token robado |
iat | Emitido en | Detecta tokens creados antes de un cambio de contraseña |
nbf | No antes de | Tokens que solo se vuelven válidos más tarde |
Además de estos, las aplicaciones añaden sus propios claims: roles, permisos, un nombre visible. Mantén el payload pequeño: el token se envía con cada petición, así que un token de 5 KB es un impuesto en cada llamada.
Cuándo usar un JWT, y cuándo no
Los JWT brillan cuando la verificación debe ocurrir sin una consulta a la base de datos, o entre servicios que no comparten un almacén de sesiones: API, microservicios e inicio de sesión único. El verificador solo necesita la clave.
Pierden en un aspecto importante: no puedes revocarlo fácilmente. Una sesión del lado del servidor puede eliminarse en el momento en que un usuario cierra sesión o cambia su contraseña; un JWT sigue siendo válido hasta que caduca, porque no hay nada que eliminar. Las mitigaciones estándar son tiempos de caducidad cortos (minutos, no días) más tokens de actualización — un token de larga duración que solo se envía al endpoint de inicio de sesión para crear JWT nuevos de corta duración — o una lista de revocación, que reintroduce silenciosamente la consulta a la base de datos que el JWT debía evitar.
Regla general: si tienes una app y una base de datos, una cookie de sesión clásica es más sencilla y segura. Recurre a JWT cuando tengas muchos servicios o cuando el token deba cruzar un límite de confianza.
Errores comunes
- Confiar en un token decodificado por el cliente. Decodificar no demuestra nada: solo lo hace la verificación de la firma. El
admin: truede un payload decodificado es un claim, no un hecho, hasta que la firma se verifica. - Aceptar
alg: none. Un token sin firma debe rechazarse. Las bibliotecas que aún lo aceptan son la vulnerabilidad JWT más antigua que existe, y todavía aparece. - Secretos débiles o filtrados. HS256 con el secreto
secretse puede falsificar en segundos. Usa un secreto largo y aleatorio, rótalo y no lo subas nunca al repositorio. - Sin caducidad (
exp). Un token robado funciona para siempre. Establece unexpcorto y usa tokens de actualización. - Poner secretos en el payload. Base64url no es cifrado: cualquiera puede leerlo. Ver el recuadro anterior.
- Guardar tokens en localStorage. Cualquier agujero de cross-site scripting (XSS) permite a un atacante leerlo. Las cookies HttpOnly son un hogar más seguro para los tokens del navegador.
Pruébalo: decodificador JWT
Pega un token en el decodificador JWT y mira cómo se divide en encabezado, payload y fechas legibles: la forma más rápida de ver la estructura que describe esta guía.
Sigue aprendiendo
Preguntas frecuentes
¿Está cifrado un JWT?
No. Un JWT estándar (JWS) está firmado, no cifrado: el payload es base64url, que cualquiera puede decodificar. El cifrado es un formato aparte, JWE, que se usa cuando el contenido en sí debe mantenerse secreto.
¿Cómo revoco un JWT cuando un usuario cierra sesión?
No puedes eliminarlo directamente: sigue siendo válido hasta exp. Las respuestas prácticas son una caducidad corta con tokens de actualización, o una lista de denegación en el servidor con los ID de los tokens revocados (el claim jti) verificada en los endpoints sensibles.
¿JWT o cookie de sesión? ¿Cuál debo elegir?
Una cookie de sesión para una sola app con base de datos: más sencilla y revocable al instante. Un JWT para API y microservicios donde los verificadores no pueden compartir un almacén de sesiones, o donde los tokens cruzan límites entre servicios. Muchos sistemas usan ambas: una sesión para el navegador y JWT para las llamadas entre servicios.
¿Dónde debo guardar un JWT en el navegador?
En una cookie HttpOnly, Secure y SameSite: JavaScript no puede leerla, así que XSS no puede robarla. localStorage es cómodo, pero cualquier script de la página puede leerlo, incluido uno inyectado.
¿Puedo decodificar un JWT sin el secreto?
Sí: decodificar el encabezado y el payload no necesita ninguna clave; solo verificar la firma la necesita. Por eso la herramienta decodificadora de JWT puede mostrarte el contenido de un token al instante, y por eso no debes poner nunca secretos en el payload.