Cómo decodificar un JWT y leer sus claims de forma segura
Decodifica un JWT separando sus tres segmentos base64url, lee claims como iss, sub y exp, y aprende por qué decodificar un token no es lo mismo que verificarlo.
Actualizado
Un JWT son tres segmentos codificados en base64url y separados por puntos: cabecera, payload y firma. Para leer los claims, divide por ., decodifica en base64url los dos primeros segmentos y analiza el JSON resultante. Decodificar no requiere ninguna clave, pero tampoco demuestra nada; solo la verificación de la firma te dice que el token es auténtico.
Anatomía de un token
Un JWT típico tiene este aspecto: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0IiwibmFtZSI6IkFkYSIsImlhdCI6MTUxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c. Las tres partes son:
- Cabecera:
{"alg":"HS256","typ":"JWT"}. Indica qué algoritmo firmó el token y, opcionalmente, un identificador de clave (kid). - Payload:
{"sub":"1234","name":"Ada","iat":1516239022}. Los claims, que son los datos que de verdad te interesan. - Firma: bytes producidos al firmar
header.payloadcon la clave del emisor. No es JSON, así que no se decodifica en nada legible.
La cabecera de todo JWT empieza por eyJ porque así se codifica {" en Base64. Si ves eyJ, casi con seguridad estás ante un JWT.
Decodificar a mano
Los segmentos usan base64url, no Base64 estándar: - en lugar de +, _ en lugar de /, y sin relleno con =. La mayoría de los decodificadores acepta el alfabeto seguro para URL, pero algunos insisten en el relleno. Para decodificar en una herramienta estricta, reemplaza los caracteres y añade = hasta que la longitud sea múltiplo de cuatro. Después decodifica y tendrás texto JSON.
En JavaScript, la versión rápida es JSON.parse(atob(token.split(".")[1].replace(/-/g,"+").replace(/_/g,"/"))). En Python, base64.urlsafe_b64decode(seg + "=" * (-len(seg) % 4)) resuelve por ti la aritmética del relleno. En la línea de comandos, cut -d. -f2 | base64 -d funciona una vez corregido el relleno.
Si solo quieres ver qué hay dentro sin escribir código, pega el token en el decodificador de JWT. Separa los segmentos, decodifica la cabecera y el payload, explica cada claim estándar y muestra una cuenta regresiva hasta la expiración.
Para inspeccionar tú mismo los bytes de un solo segmento, suéltalo en el decodificador Base64 después de corregir el relleno; la salida es el texto JSON sin procesar.
Los claims que te vas a encontrar
Los claims registrados son nombres cortos definidos en el RFC 7519. Los más comunes:
iss(emisor): quién creó el token, normalmente una URL comohttps://accounts.example.com.sub(sujeto): el usuario o la entidad de la que trata el token.aud(audiencia): para quién está destinado el token. Tu API debería rechazar los tokens cuyoaudno coincida con ella.exp(expiración): marca de tiempo Unix en segundos a partir de la cual el token no es válido.nbf(no antes de): el token no es válido antes de ese momento.iat(emitido en): cuándo se creó.jti: identificador único del token, usado para evitar la reutilización.
Todo lo demás es personalizado: email, roles, scope, tenant_id y así sucesivamente. Los claims personalizados significan lo que el emisor diga que significan, así que consulta la documentación de tu proveedor de identidad en lugar de adivinar.
Las marcas de tiempo van en segundos, no en milisegundos. 1516239022 es el 18 de enero de 2018. Un valor como 1516239022000 es un error del lado del emisor, y cualquier validador correcto lo leerá como una fecha a decenas de miles de años de distancia.
Decodificar no es verificar
Esta es la parte en la que la gente se equivoca. Cualquiera puede construir un token con {"sub":"admin","roles":["superuser"]} en el payload y cualquier cadena en el lugar de la firma. Se decodifica perfectamente. Tampoco vale nada a menos que la firma se compruebe con la clave del emisor.
La verificación depende de alg:
HS256,HS384,HS512: HMAC con un secreto compartido. Quien verifica necesita el mismo secreto que usó el emisor. La firma es un resumen HMAC-SHA deheader.payload; un generador de hashes muestra qué aspecto tiene un resumen SHA-256 simple, pero HMAC además mezcla la clave, así que la verificación corresponde a una biblioteca en tu servidor.RS256,ES256,PS256: asimétricos. El emisor firma con una clave privada; tú verificas con la clave pública, que normalmente se obtiene de un endpoint JWKS como/.well-known/jwks.jsony se empareja porkid.none: sin firma. Recházalos sin más.
Usa una biblioteca mantenida (jsonwebtoken o jose en Node, PyJWT en Python, java-jwt en la JVM) y pásale la lista de algoritmos esperados, el emisor y la audiencia. Nunca dejes que la propia cabecera alg del token decida cómo se verifica; ese es el origen de varios bypasses reales.
Decodifica para depurar. Verifica para confiar. Un claim decodificado es una pista sobre lo que pretendía el emisor, no una prueba de nada, hasta que la firma se haya comprobado en el servidor.
Manejo seguro mientras depuras
Un JWT es una credencial al portador: quien la tenga puede usarla hasta que caduque. Pega tokens solo en herramientas que se ejecuten en el navegador y no los transmitan. Cuando los compartas en tickets, es preferible que sean tokens caducados o de un entorno de staging. Quita el segmento de la firma antes de publicar un token en un chat; los dos primeros segmentos siguen mostrando los claims y el token ya no se puede usar.
Hay más herramientas de decodificación e inspección en la categoría para desarrolladores.
Pruébalo
Pega un token en el decodificador de JWT para ver la cabecera, cada claim con una breve explicación, el algoritmo de firma y cuánto falta para exp. Nada sale de tu navegador.