Qué es un JWT
Un JSON Web Token (JWT, RFC 7519) es una cadena compacta que transporta un header y un payload JSON, opcionalmente protegidos por una firma o cifrado autenticado. La forma firmada habitual son tres segmentos Base64URL separados por puntos:
base64url(header) . base64url(payload) . base64url(signature)
El payload suele incluir claims como sujeto (sub), audiencia (aud), expiración (exp) y campos de la aplicación. Como el payload de un JWT firmado (no cifrado) solo está codificado, quien obtenga el token puede leer los claims. La firma detecta manipulación y, con un secreto compartido o clave pública, confirma quién emitió el token.
Inspeccione un token de ejemplo con la herramienta Decodificar JWT: decodificar solo no demuestra que la firma sea válida.
Subherramientas de esta familia
- Decodificar JWT — divide y decodifica en Base64URL el header y el payload para leer algoritmos y claims en el navegador.
- Firmar JWT HS256 — construye un token a partir de un payload JSON y un secreto compartido con HMAC-SHA256.
- Verificar JWT HS256 — recalcula la firma HMAC-SHA256 con su secreto e indica si coincide.
Ruta de aprendizaje típica: firmar un payload desechable, decodificarlo para inspeccionar claims y verificar con el mismo secreto. Cambiar cualquier carácter del payload debe hacer fallar la verificación.
HS256 y el papel de HMAC
HS256 significa HMAC-SHA256 sobre los segmentos de header y payload. Emisor y verificador comparten un secreto. Ese modelo encaja en APIs de primera parte y tokens de sesión simples. Encaja mal cuando muchos clientes no confiables deben verificar tokens sin el secreto del emisor: ahí necesita algoritmos asimétricos (RS256, ES256) con un JWKS público.
La verificación HS256 solo es tan fuerte como el almacenamiento del secreto. Embebido en una app móvil pública o un bundle frontend, cualquiera puede falsificar tokens.
Para la construcción MAC subyacente, vea también el hub HMAC, en especial HMAC SHA-256.
Claims que debe tratar con cuidado
exp / nbf / iat. Las ventanas de expiración y not-before evitan el reuso indefinido. Los verificadores deben rechazar tokens caducados; los decodificadores que solo imprimen JSON no aplican el tiempo por usted.
alg. El header anuncia el algoritmo. Codifique en duro el algoritmo esperado en el verificador (solo HS256, por ejemplo). Vulnerabilidades históricas aceptaron alg: none o cambiaron de RS256 a HS256 tratando una clave pública como secreto HMAC.
aud e iss. Las comprobaciones de audiencia e emisor impiden que tokens emitidos para un servicio sean aceptados por otro.
Datos sensibles en el payload. Prefiera identificadores opacos a datos personales en bruto en JWT no cifrados. Recuerde que logs, historial del navegador y cabeceras Referer pueden filtrar tokens.
Decodificar frente a verificar
| Operación | Demuestra legibilidad | Demuestra autenticidad |
|---|---|---|
| Decodificar | Sí (JWT no cifrado) | No |
| Verificar HS256 | Necesita secreto | Sí, si el secreto es correcto y la comparación es sólida |
Verifique siempre en las rutas de código que autorizan acciones. Decodificar en un depurador es para humanos; la verificación criptográfica es para máquinas que deciden el acceso.
Detalles de Base64URL
JWT usa Base64URL sin relleno en la serialización clásica. Eso difiere del Base64 estándar (+// frente a -/_). Mezclar alfabetos al reconstruir tokens a mano es una fuente habitual de errores de firma inválida. Prefiera APIs de biblioteca que gestionen la codificación en producción.
Fallos habituales
- Desfase de reloj: un token recién emitido parece «aún no válido» o ya caducado—permita un pequeño margen si su plataforma lo documenta.
- UTF-8 y canonización JSON: volver a firmar tras embellecer el JSON cambia los bytes y rompe firmas.
- Secreto distinto entre entornos (staging frente a producción).
- Tratar el éxito de la decodificación como éxito de inicio de sesión.
- Poner contraseñas o datos de tarjeta en claims JWT.
Limitaciones y entorno
Estas herramientas se centran en aprender y depurar HS256. No implementan todo el stack JOSE (cifrado JWE, cada algoritmo JWA o federación JWKS). El procesamiento en el cliente mantiene tokens de muestra en el dispositivo; aun así evite pegar tokens de sesión de producción en máquinas compartidas.
Resumen
Los JWT empaquetan claims en una cadena compacta y firmada. Este hub permite decodificar headers y payloads, firmar con HS256 y verificar firmas HMAC-SHA256. Lea los claims con cautela, verifique antes de confiar, proteja los secretos compartidos y elija algoritmos asimétricos cuando los verificadores no deban compartir la clave del emisor.