Como decodificar un JWT (y por que decodificar no es verificar)

Estas depurando un flujo de autenticacion y alguien te entrega una larga cadena de caracteres ilegibles: eyJhbGciOi.... Eso es un JSON Web Token, o JWT, y dentro hay datos estructurados que puedes leer en segundos una vez que sabes como. Esta guia explica de que esta hecho un JWT, como decodificarlo para inspeccionar sus claims y el punto de seguridad que confunde constantemente a los desarrolladores: decodificar un token no es lo mismo que verificarlo. Puedes seguir el proceso con el Decodificador de JWT gratuito.

De que esta hecho un JWT

Un JWT es una forma compacta de transportar informacion firmada entre dos partes, casi siempre para demostrar quien es un usuario despues de que inicia sesion. Si miras de cerca, veras que se divide en tres partes separadas por puntos:

header.payload.signature

Cada una de las dos primeras partes es un objeto JSON codificado en Base64url, por lo que parece una serie de caracteres aleatorios en lugar de texto legible. Las tres piezas son:

• Header (cabecera). Un pequeno JSON que describe el token, principalmente el algoritmo de firma (como HS256 o RS256) y el tipo de token.
• Payload (carga util). La parte interesante. Aqui se guardan los claims: quien es el usuario, cuando se emitio el token, cuando expira y cualquier dato personalizado que haya agregado el emisor.
• Signature (firma). Un sello criptografico creado a partir de la cabecera, la carga util y una clave secreta. Es lo que permite a un servidor confirmar que el token no fue manipulado.

Los puntos son separadores literales, por lo que un JWT siempre son tres bloques Base64url unidos por puntos.

Como decodificar y leer los claims

Decodificar simplemente invierte la codificacion Base64url de la cabecera y la carga util para que puedas leer el JSON que contienen. El Decodificador de JWT gratuito hace esto al instante y, lo que es importante, se ejecuta por completo en tu navegador, por lo que el token que pegas nunca se envia a ningun sitio.

1. Copia el token completo, las tres partes incluyendo los puntos.
2. Pegalo en el Decodificador de JWT.
3. Lee la cabecera y la carga util decodificadas como JSON con formato.

En la carga util veras a menudo claims estandar: sub para el sujeto (normalmente un id de usuario), iat para la hora de emision, exp para la expiracion e iss para el emisor. Los valores de tiempo suelen ser marcas de tiempo Unix. Leerlos es la forma mas rapida de responder preguntas como ‘este token ha expirado?’ o ‘para que usuario es?’ mientras depuras.

Decodificar no es verificar

Aqui esta el punto que vale la pena grabar en la memoria. Cualquiera que tenga el token puede decodificar la cabecera y la carga util, sin clave ni contrasena. La codificacion es reversible por diseno, exactamente igual que Base64. Decodificar te dice lo que el token afirma, pero no te dice nada sobre si esas afirmaciones son fiables.

Verificar es un paso separado y criptografico. Un servidor vuelve a calcular la firma usando la clave secreta o publica y comprueba que coincide con la firma del token. Solo una firma valida demuestra que el token fue emitido por quien dice y que no ha sido alterado. Un decodificador no puede hacer esto por ti, porque no tiene la clave. Asi que nunca decidas que ‘este usuario esta autenticado’ basandote solo en una decodificacion, esa comprobacion tiene que ocurrir en el servidor con la clave adecuada.

Nunca pongas secretos en la carga util

Como la carga util es trivialmente legible por cualquiera que tenga el token, es el lugar equivocado para algo sensible. No pongas contrasenas, claves de API ni datos personales privados en la carga util de un JWT, ya que es efectivamente publica para cualquiera que intercepte o reciba el token. La firma evita la manipulacion, no la lectura. Trata la carga util como visible por defecto y manten los secretos del lado del servidor.

Herramientas relacionadas para inspeccionar tokens

Decodificar un JWT a menudo conduce a unas pocas tareas vecinas. Si quieres entender la propia capa Base64url, la herramienta de codificar y decodificar Base64 te permite experimentar con la misma codificacion que usa el token. Una vez que tengas una carga util decodificada, el Formateador de JSON la indentara y ordenara para que un conjunto de claims muy anidado sea facil de leer. Y si estas razonando sobre como se construye la firma, el Generador de Hash es una buena forma de ver como se comporta el hashing unidireccional, ya que la firma se apoya en primitivas criptograficas relacionadas.

La version corta

Un JWT son tres partes codificadas en Base64url, cabecera, carga util y firma, unidas por puntos. Decodificar invierte la codificacion para que puedas leer los claims, lo cual es perfecto para depurar. Solo recuerda que decodificar no es verificar: la carga util es legible por cualquiera, asi que nunca guardes secretos en ella, y siempre verifica la firma en el servidor antes de confiar en un token. Cuando necesites inspeccionar uno de forma rapida y privada, el Decodificador de JWT gratuito lo lee directamente en tu navegador.