¿Qué es un JWT? Estructura, claims y decodificación

Qué es un JWT

¿Qué es un JWT? Estructura, claims y un decodificador privado | We.Inc

JSON Web Tokens explicados: header, payload y firma, los siete claims registrados del RFC 7519, los riesgos de seguridad y un decodificador que nunca envía tu token a ningún sitio.

Un JWT (JSON Web Token) es una cadena compacta y segura para URLs formada por tres partes en base64url separadas por puntos: un header que indica el algoritmo, un payload con claims como sub y exp, y una firma. Cualquiera puede decodificar y leer el payload; solo la firma, comprobada con la clave correcta, demuestra que nadie lo ha modificado.

Nombres de claims registrados (RFC 7519, sección 4.1)

Claim
Nombre
Significado

Emisor
Quién emitió el token

Sujeto
A quién se refiere el token, normalmente un id de usuario

Audiencia
Qué destinatarios deben aceptarlo

Momento de expiración
Rechazar a partir de este momento

No antes de
Rechazar antes de este momento

Emitido en
Cuándo se creó el token

ID del JWT
Un id único, útil para bloquear la reutilización

Pega un token en el decodificador de abajo para ver su header y su payload, con cada claim registrado explicado y cada marca de tiempo convertida en una fecha legible. La decodificación ocurre en el propio JavaScript de esta página, así que el token nunca se sube. Eso importa, porque un token activo es una llave a la cuenta de alguien.

El decodificador divide el token por sus puntos y espera tres partes (un JWE con cinco partes está cifrado y no se puede leer).
Convierte las dos primeras partes de base64url a texto y las analiza como JSON.
Los claims registrados reciben una etiqueta, y exp, nbf e iat se muestran como fechas indicando si el token es válido ahora.
La firma se muestra pero no se comprueba: para eso hace falta la clave del emisor, que debe estar en tu servidor.

Nunca pongas secretos ni datos personales en un payload. Firmar impide modificaciones; no oculta nada.
Fija los algoritmos que acepta tu servidor. Nunca dejes que decida el header alg del propio token, y rechaza none.
Comprueba siempre exp, iss y aud, no solo la firma, para que se rechace un token pensado para otro servicio.
Las claves HS256 deben ser bytes aleatorios largos. El RFC 8725 dice que no se deben usar directamente contraseñas fáciles de recordar.
Haz que los tokens de acceso duren poco y renuévalos, porque un JWT robado sigue siendo válido hasta que expira.

Preguntas frecuentes

¿Es seguro decodificar un JWT en línea?

Solo si la decodificación ocurre en tu navegador. El token es una credencial: cualquiera que tenga uno válido puede usar la API como ese usuario hasta que expire. El decodificador de esta página funciona en local y no envía nada, pero con tokens de producción lo más seguro es acostumbrarse a decodificar solo tokens de prueba.

¿Está cifrado un JWT?

Un JWT firmado normal (un JWS) no lo está. Su payload solo está codificado en base64url, algo que cualquiera puede revertir. Existen tokens cifrados, los JWE, con cinco partes separadas por puntos en lugar de tres, pero la mayoría de los tokens de inicio de sesión y de API están firmados, no cifrados.

¿En qué formato están exp e iat?

NumericDate: segundos enteros desde 1970-01-01T00:00:00Z, sin contar segundos intercalares. Date.now() de JavaScript devuelve milisegundos, así que divide entre 1000 antes de comparar, un error muy habitual.

¿Guardo un JWT en localStorage o en una cookie?

Cualquier script que se ejecute en la página puede leer localStorage, así que un solo fallo de cross-site scripting puede robar el token. Una cookie HttpOnly, Secure y SameSite lo mantiene fuera del alcance de los scripts, a cambio de tener que gestionar CSRF. Muchos equipos eligen la cookie para las sesiones del navegador.

¿Puedo cerrar la sesión de un usuario con un JWT?

No por sí solo, porque el token sigue siendo válido hasta exp. Usa una expiración corta más refresh tokens que puedas revocar, o mantén una lista de bloqueo de valores jti para los tokens que deban morir antes.

Las tres partes

El header es un pequeño objeto JSON como {"alg":"HS256","typ":"JWT"}. El payload contiene los claims. Cada uno está codificado en base64url, que es base64 con - y _ en lugar de + y / y sin relleno =, así que el resultado es seguro en URLs y cabeceras.
La firma se calcula sobre las dos primeras partes codificadas unidas por un punto. Cambia un carácter del payload y la firma deja de coincidir.

Algoritmos de firma

HS256 usa un único secreto compartido tanto para firmar como para verificar, así que cada servicio que comprueba tokens también puede crearlos. RS256 y ES256 firman con una clave privada y verifican con una clave pública, lo que encaja con configuraciones en las que muchos servicios verifican pero solo uno emite.

Errores que todavía provocan brechas

Los tokens sin proteger con alg none no llevan ninguna firma. Una librería que confía en el header puede ser engañada para aceptar uno, o para tratar una clave pública RSA como un secreto HMAC. El RFC 8725 indica a las librerías que dejen que quien las usa fije los algoritmos permitidos, y tú deberías hacerlo.

Decodificar y verificar en código

Decodificar un payload en JavaScript puro

Lee los claims sin verificarlos. Sirve para mostrar un nombre de usuario en la UI, nunca para decidir el acceso.

Verificar en el servidor con jose

jwtVerify comprueba la firma, exp y nbf, y con estas opciones también el emisor, la audiencia y el algoritmo permitido.

Decodificador de JWT privado

Pega un token para leer su header y su payload. La decodificación se hace en tu navegador; el token no se envía, no se guarda y no se registra.

Quién emitió el token

A quién se refiere el token, normalmente un id de usuario

Qué destinatarios deben aceptarlo

Rechazar a partir de este momento

Rechazar antes de este momento

Cuándo se creó el token

Un id único, útil para bloquear la reutilización

JWT

Cargar token de ejemplo

Borrar

Header

Payload

Firma (no se verifica aquí)

Claims explicados

Claim

Valor

Significado

Claim personalizado

Un JWT firmado tiene 3 partes separadas por puntos; este tiene {n}.

5 partes significa un JWE cifrado, que no se puede leer sin la clave.

La parte {n} no es JSON válido en base64url.

Expiró {v}

Válido hasta {v}

No es válido hasta {v}

alg es none: este token no tiene firma y debe rechazarse.

Decodificado en local. Nada sale de esta página.

Empieza gratis · Sin tarjeta de crédito