Un JSON Web Token suele parecer texto aleatorio, pero un JWT firmado común está diseñado para ser legible. Su header y payload son JSON codificado con Base64URL, no cifrado por defecto. Decodificar esas dos partes permite diagnosticar problemas de issuer, audience, scope o expiración. Sin embargo, no demuestra que el token sea auténtico. Entender esa diferencia es la base de una depuración segura.

Esta guía se centra en JWT compactos con tres secciones separadas por puntos, la forma habitual de access tokens e identity tokens firmados. Explica qué revela un decoder, qué significan los claims registrados y qué comprobaciones todavía debe ejecutar una librería de verificación dentro de un entorno confiable.

Reconoce las tres partes de un JWT

Un JWT firmado típico tiene la forma header.payload.signature. El header declara metadatos como el algoritmo de firma y, a veces, un identificador de clave. El payload contiene claims: afirmaciones con nombre y valor sobre el sujeto, emisor, destinatario, tiempos, permisos o datos propios de la aplicación. La firma protege el header y el payload codificados frente a modificaciones no detectadas.

El estándar JWT, RFC 7519, también contempla formas cifradas y anidadas. Por eso no todos los tokens se entienden dividiéndolos en tres fragmentos. Si un token compacto tiene cinco secciones, probablemente es un JWE y requiere la clave y la librería de descifrado correspondientes.

Decodifica Base64URL correctamente

Base64URL es una variante de Base64 compatible con URLs. Sustituye por - y _ caracteres incómodos en una URL y normalmente omite el padding =. El decoder debe restaurar o tolerar ese padding y decodificar JSON UTF-8. Procesar un segmento como Base64 estándar sin esos ajustes hace que un token válido parezca defectuoso.

Después, parsea ambas secciones como JSON. Un header puede incluir {"alg":"RS256","typ":"JWT","kid":"key-7"}; el payload puede contener iss, sub, aud, exp y claims personalizados. Formatear el JSON facilita la lectura, pero no utiliza la firma ni una clave secreta.

Interpreta los claims registrados en contexto

iss identifica al emisor, sub al sujeto dentro del contexto de ese emisor y aud al destinatario o destinatarios previstos. exp marca la expiración, nbf indica que no debe aceptarse antes de cierto instante e iat registra cuándo se emitió. jti aporta un identificador del token que puede ayudar en controles de replay o revocación.

Esos nombres no se validan solos. Un token de otra API puede estar bien firmado y no haber expirado, pero seguir siendo inválido para tu servicio porque su audience es incorrecto. Un subject no es necesariamente un email ni una cuenta global. Interpreta cada claim según el contrato del issuer y no concedas acceso por un campo personalizado desconocido solo porque aparezca en el payload.

Convierte los timestamps del JWT sin adivinar

Las numeric dates de JWT cuentan segundos enteros o fraccionarios desde el Unix epoch. Los valores Date de JavaScript usan milisegundos, por lo que hay que multiplicar el claim por 1.000 antes de construir la fecha. Un número como 1710000000 es razonable en segundos; interpretarlo como milisegundos genera una fecha próxima a enero de 1970. Tratar 13 dígitos de milisegundos como segundos produce una fecha absurdamente futura.

Muestra primero el resultado en UTC para que el instante sea inequívoco y, si hace falta, añade la hora local. El código de verificación puede admitir una tolerancia pequeña por diferencias de reloj entre sistemas, pero debe ser explícita y limitada. Ver la expiración en el navegador sirve para diagnosticar; el servidor sigue siendo responsable de aplicarla.

Decodificar no es verificar la firma

Cualquiera puede generar texto Base64URL nuevo y sustituir el payload. Un decoder mostrará esos claims modificados igual que los legítimos. La verificación combina el header y payload codificados exactos, la firma, un algoritmo permitido y una clave confiable asociada al issuer esperado. Si alguna parte cambió, una verificación correcta falla.

Nunca aceptes el algoritmo del header como una instrucción sin restricciones. Configura los algoritmos admitidos por la aplicación, consigue las claves por una ruta confiable, gestiona su rotación y valida issuer y audience después de la comprobación criptográfica. Una librería JWT madura implementa estas reglas con más seguridad que código de verificación escrito a mano.

No pegues bearer tokens reales en sitios desconocidos

Un access token puede ser una credencial bearer: quien lo posee puede utilizarlo hasta que expire o sea revocado. El payload legible también puede revelar identificadores internos, tenants, roles o datos personales. Para depurar, prefiere un decoder local que no transmita el token o genera uno sintético en un entorno que no sea producción.

Si un token real se compartió con un servicio no confiable, quedó en una issue pública o se incluyó en un repositorio, considéralo expuesto. Revócalo cuando sea posible, rota las credenciales relacionadas si corresponde y elimínalo de logs e historiales. Ocultar únicamente la firma no garantiza privacidad, porque el payload puede contener información sensible.

Checklist completa de validación JWT

Aceptar un token en producción requiere más que comprobar exp. Verifica la firma con un algoritmo permitido de forma explícita y una clave confiable. Exige issuer y audience esperados. Aplica expiración y not-before con una tolerancia de reloj controlada. Confirma que tipo, scopes, roles, nonce u otros claims de aplicación corresponden a la operación actual. Añade revocación o controles de replay cuando el modelo de amenazas lo exija.

Distingue además access tokens de ID tokens. Un token emitido para informar al cliente quién inició sesión no se convierte automáticamente en autorización para una API. Los perfiles añaden reglas al formato JWT básico, así que sigue la documentación del proveedor de identidad y los requisitos de validación OAuth u OpenID Connect relevantes.

Usa el decoder como herramienta de inspección

Un decodificador JWT responde muy bien preguntas concretas: ¿qué issuer generó el token?, ¿la audience es correcta?, ¿cuándo expira?, ¿qué key ID solicita?, ¿incluye el scope esperado? No es un motor de decisiones de autenticación.

El modelo mental seguro es “decodifica para inspeccionar, verifica para confiar”. Mantén privados los tokens de producción, convierte con cuidado las numeric dates y deja la validación criptográfica y de claims a una librería mantenida en el servidor. Con esos límites, decodificar es una técnica rápida sin convertir datos legibles en hechos asumidos.