Cómo decodificar tokens JWT: Guía completa

Los tokens JSON Web (JWT) son tokens compactos y seguros para URL que se utilizan para autenticación e intercambio de información en aplicaciones web modernas. Un JWT consta de tres partes codificadas en Base64URL separadas por puntos: el encabezado, el payload y la firma. Decodificar un JWT revela los claims y metadatos internos, ayudándote a depurar flujos de autenticación, inspeccionar permisos y entender la expiración del token sin realizar llamadas adicionales a la API.

El encabezado contiene metadatos sobre el token en sí, típicamente especificando el algoritmo de firma (como HS256 o RS256) y el tipo de token (JWT). Esto le indica al sistema de verificación qué método criptográfico usar al comprobar la firma. Decodificar el encabezado es tan simple como decodificar en Base64URL la primera parte del token y analizar el JSON resultante. El algoritmo especificado aquí determina cómo debe validarse la firma en la tercera parte.

La sección de payload contiene los claims reales: pares clave-valor que describen al usuario, permisos y validez del token. Los claims estándar incluyen 'iss' (emisor), 'sub' (sujeto/ID de usuario), 'aud' (audiencia), 'exp' (marca de tiempo de expiración), 'nbf' (no antes de), e 'iat' (emitido en). Se pueden agregar claims personalizados para datos específicos de la aplicación como roles, permisos o identificadores de sesión. Decodificar el payload te da acceso inmediato a esta información sin contactar al servidor de autenticación.

La firma es un hash criptográfico creado combinando el encabezado codificado, el payload codificado y una clave secreta (para HMAC) o clave privada (para RSA/ECDSA). Esta firma asegura que el token no ha sido manipulado: si alguien modifica el encabezado o el payload, la firma se vuelve inválida. Aunque puedes decodificar el encabezado y el payload sin la clave secreta, no puedes verificar la autenticidad de la firma sin ella. La verificación es esencial en producción; la decodificación sola es útil para depuración.

Decodificar un JWT es sencillo: divide el token en el carácter de punto, decodifica en Base64URL las dos primeras partes y analiza el JSON resultante. La tercera parte son los bytes de firma en bruto, que típicamente no decodificas manualmente. Los decodificadores JWT en línea y las herramientas del navegador automatizan este proceso, mostrando el encabezado y el payload en formato legible. Esto es seguro para desarrollo y depuración, pero nunca pegues tokens de producción que contengan datos sensibles en herramientas de terceros.

Inspeccionar la expiración del JWT es crítico para depurar problemas de autenticación. El claim 'exp' contiene una marca de tiempo Unix que indica cuándo el token se vuelve inválido. Si el tiempo actual está más allá de esta marca, el token ha expirado y el servidor debería rechazarlo. Las aplicaciones front-end pueden decodificar tokens del lado del cliente para verificar la expiración antes de hacer solicitudes a la API, reduciendo llamadas de red innecesarias y proporcionando mejores mensajes de error a los usuarios.

Los tokens JWT no están encriptados por defecto: solo están firmados. Esto significa que cualquiera puede decodificar y leer el contenido, así que nunca debes incluir información sensible como contraseñas, números de tarjetas de crédito o identificadores personales en el payload. Solo incluye datos que sea aceptable que los clientes vean. Si necesitas transmitir claims sensibles, usa JWT encriptados (JWE), que agregan una capa de encriptación sobre la estructura JWT estándar.

Al depurar fallos de autenticación, decodificar el JWT ayuda a identificar problemas comunes: tokens expirados, claims de audiencia incorrectos, campos requeridos faltantes o discrepancias de algoritmo. Compara los claims del token con los requisitos de tu API para identificar dónde falla la validación. Muchos frameworks proporcionan mensajes de error detallados, pero examinar el token directamente a menudo revela la causa raíz más rápido que leer logs del servidor.

Puedes decodificar JWT programáticamente en cualquier lenguaje. JavaScript proporciona decodificación Base64 incorporada a través de atob() o Buffer, mientras que bibliotecas como jsonwebtoken manejan tanto decodificación como verificación. PyJWT de Python, firebase/php-jwt de PHP y bibliotecas similares en otros lenguajes ofrecen métodos de una línea para decodificar y validar tokens. Para sistemas en producción, siempre verifica las firmas y valida los claims: decodificar sin verificación solo es apropiado para depuración y desarrollo.