GameParticles
Desarrollo

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.payload con 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 como https://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 cuyo aud no 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 de header.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.json y se empareja por kid.
  • 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.

Herramientas de esta guía

Preguntas frecuentes

¿Por qué todos los JWT empiezan por eyJ?

Porque la cabecera es JSON que empieza con una llave y una comilla doble, y los caracteres {" se codifican como eyJ en Base64. El mismo prefijo suele aparecer también al inicio del segmento del payload.

¿Puedo verificar la firma de un JWT en el navegador?

Solo puedes verificar un token RS256 o ES256 si tienes la clave pública del emisor. Los tokens HS256 necesitan el secreto compartido, que nunca debería estar en un navegador. En la práctica, verifica en el servidor con una biblioteca mantenida.

¿El claim exp está en segundos o en milisegundos?

En segundos desde la época Unix, según el RFC 7519. Un valor de 13 dígitos es una marca de tiempo en milisegundos e indica un error en el lado emisor.

¿Es seguro pegar un JWT en un decodificador online?

Solo si el decodificador se ejecuta en el lado del cliente y no envía nada a un servidor. Aun así, es preferible usar tokens caducados o de staging, porque un JWT activo es una credencial al portador que le sirve a cualquiera que la tenga.

Más guías para desarrolladores

Formateador de JSON
Desarrollo · Formatea, valida y minifica JSON con resaltado de sintaxis.
↵
Codificar / decodificar Base64
Desarrollo · Codifica texto en Base64 o decodifica Base64 a texto plano.
↵
Codificador / Decodificador de URL
Desarrollo · Codifica o decodifica componentes de URL y cadenas de consulta.
↵
Generador de hash
Desarrollo · Genera hashes MD5, SHA-1, SHA-256 y SHA-512.
↵
Generador de UUID
Desarrollo · Genera UUID v4 (aleatorios) en lote con un clic.
↵
Probador de regex
Desarrollo · Prueba expresiones regulares sobre un texto con resaltado de coincidencias en vivo.
↵
Contador de palabras
Texto · Cuenta palabras, caracteres, frases, párrafos y tiempo de lectura.
↵
Conversor de mayúsculas y minúsculas
Texto · Convierte texto a MAYÚSCULAS, minúsculas, Título, camelCase, snake_case y más.
↵
Ordenador de listas
Texto · Ordena, invierte, baraja y quita duplicados de listas de texto.
↵
Vista previa de Markdown
Texto · Escribe Markdown y mira la vista previa renderizada en vivo, lado a lado.
↵
Calculadora de porcentajes
Números · Calcula porcentajes, aumentos, descuentos y qué % es un número de otro.
↵
Conversor de colores
Colores · Convierte colores entre HEX, RGB, HSL y HSV al instante.
↵
Snake
Arcade · Come, crece y no choques con las paredes. Un clásico eterno.
↵
2048
Puzles · Desliza y combina fichas hasta conseguir la legendaria ficha 2048.
↵
Word Grid
Puzles · Adivina la palabra oculta de cinco letras en seis intentos con pistas de colores.
↵
Sudoku
Puzles · Completa la cuadrícula 9x9 con lógica. Cuatro niveles, de fácil a experto.
↵
Buscaminas
Estrategia · Usa las pistas numéricas para despejar el campo de minas. Lógica clásica, tres niveles.
↵
Breakout
Arcade · Rompe todos los ladrillos con barra y bola. Power-ups, combos y niveles sin fin.
↵
Práctica de mecanografía
Casual · Mejora tus PPM y tu precisión con prácticas de 30 segundos a 5 minutos. Descubre tus teclas débiles.
↵
TypeRunner
Arcade · Carrera de mecanografía multijugador. Reta a tus amigos con un enlace, vence a la máquina o persigue a tu fantasma.
↵
Typing Blocks
Arcade · Escribe cada palabra antes de que su bloque de madera aterrice. Si fallas, la pila sube hacia la línea.
↵
Bubble Shooter
Arcade · Apunta, rebota en las paredes y explota grupos de tres o más burbujas.
↵
Road Rush
Arcade · Corre contra siete rivales entre el tráfico y ábrete paso a golpes.
↵