Codificador JWT en línea: crear y firmar tokens sin instalar nada

Cada desarrollador aprende qué es un JWT aproximadamente en el mismo momento: la primera vez que tienen que implementar autenticación y alguien lo sugiere. Lees el RFC, miras el payload decodificado en base64, piensas "ah, eso es solo JSON" — y luego pasas la siguiente hora confundido sobre qué hace exactamente la parte de la firma y por qué.

La confusión es entendible. Los JWTs son simples en estructura pero sutiles en implicaciones de seguridad. Esta guía se enfoca en el lado práctico: lo que realmente necesitas saber para crear y usar JWTs para pruebas y depuración, y cómo el Codificador JWT en ToolBox Hubs te permite hacer eso sin instalar una biblioteca o levantar un servidor.

Qué es realmente un JWT

Un JSON Web Token son tres cadenas codificadas en base64url unidas por puntos: header.payload.signature.

El header identifica el tipo de token y el algoritmo de firma:

{
  "alg": "HS256",
  "typ": "JWT"
}

El payload contiene claims — básicamente pares clave-valor de información:

{
  "sub": "user_12345",
  "email": "alice@example.com",
  "role": "admin",
  "iat": 1714000000,
  "exp": 1714086400
}

La firma es un hash criptográfico del header y payload codificados, creado usando tu clave secreta. Es lo que hace que el token sea evidente al manipulación — cambia un solo carácter en el payload, y la firma ya no coincide.

Aquí está la cosa que hace tropezar a mucha gente: el payload no está cifrado. Está codificado en base64url, lo que significa que cualquiera que tenga el token puede decodificarlo y leerlo inmediatamente. La firma prueba que el token no fue manipulado, pero no hace nada para ocultar el contenido. Esto importa mucho para lo que decides poner ahí.

Los claims que realmente usas

La especificación JWT define un puñado de "claims registrados" — nombres de campos con significados estándar que las bibliotecas saben validar automáticamente.

sub (subject) — Sobre quién es el token. Usualmente un ID de usuario o identificador de cuenta. Debería ser estable y único. Un error común: poner una dirección de email aquí en lugar de un ID opaco. Las direcciones de email cambian; los IDs opacos no.

iat (issued at) — Timestamp Unix de cuándo se creó el token. Útil para depuración, y alguna lógica de validación verifica esto para rechazar tokens que parecen ser del futuro lejano (ataques de desviación de reloj).

exp (expiration) — Timestamp Unix después del cual el token debería ser rechazado. Esto es importante. Un JWT sin expiración es válido para siempre, lo que significa que si se filtra, no tienes recurso aparte de rotar el secreto enteramente. Para sesiones de corta duración, 15-60 minutos es común. Para refresh tokens, horas a días. Siempre establece esto.

iss (issuer) — Una cadena que identifica quién emitió el token. Útil en entornos multi-servicio para asegurarte de que estás validando tokens de la fuente correcta. Tu middleware de validación puede verificar que iss coincida con un valor esperado y rechazar cualquier otra cosa.

aud (audience) — Para quién está destinado el token. Previene que un token emitido para el Servicio A sea usado contra el Servicio B. A menudo un identificador de API o una lista de servicios que deberían aceptar el token.

Los claims personalizados están bien y son comunes. Si tu app necesita incrustar un role, plan, org_id o cualquier otro contexto en el token para evitar búsquedas en base de datos en cada petición, añade esos también. Solo recuerda: cualquiera puede leerlos.

Cuándo realmente usarías un codificador JWT en línea

La respuesta honesta es: no para producción. Para producción, tu servidor de auth maneja la firma — tu secreto nunca deja el entorno del servidor, y los tokens se generan programáticamente como parte de un flujo de inicio de sesión.

Donde un codificador en línea es genuinamente útil:

Probar middleware de auth sin un servidor de auth corriendo. Estás construyendo el endpoint backend que valida JWTs, y quieres probarlo manualmente. Necesitas un token válido firmado con un secreto conocido para pegar en Postman o curl. Un codificador en línea te da eso en segundos.

Mocking de auth en desarrollo local. Tu frontend está construyendo contra una API que requiere autenticación, pero el servicio de auth aún no está configurado localmente. Genera un token con los claims correctos y un secreto de prueba, codifícalo en duro en tu entorno de dev, sigue adelante. No estás desplegando esto; estás desbloqueando el desarrollo local.

Depurar fallos de validación de tokens. Un token está siendo rechazado por tu servidor y no estás seguro de por qué. ¿Está exp en el pasado? ¿Está iss mal? ¿El payload está malformado? Un codificador te permite crear un token conocido como bueno para comparar, y un decodificador JWT te permite inspeccionar el malo. Juntos forman un bucle de depuración.

Entender el comportamiento de JWT por primera vez. La mejor forma de entender lo que una biblioteca hace con un JWT es crear uno tú mismo y ver qué pasa. Modifica la expiración, cambia el algoritmo, observa qué se rompe. Una herramienta en línea hace esto práctico sin la fricción del código.

Cómo funciona la firma HS256 (sin las matemáticas)

HS256 significa HMAC-SHA256. HMAC es una construcción que usa una función hash (SHA-256 en este caso) junto con una clave secreta para producir un código de autenticación de mensaje.

El proceso en términos simples: toma el header codificado, añade un punto, añade el payload codificado. Pasa esa cadena y tu clave secreta a la función HMAC-SHA256. Obtienes un hash de longitud fija. Codifica ese hash en base64url y añádelo como la tercera parte del token.

¿Por qué funciona esto? Porque HMAC está diseñado para que sin conocer la clave secreta, no puedas producir un hash válido para un mensaje dado. Si alguien modifica el payload, no puede recalcular la firma para que coincida — necesitarían el secreto para hacer eso. Cuando tu servidor valida un JWT, vuelve a ejecutar el mismo cálculo HMAC-SHA256 sobre el header y payload que recibió, compara el resultado con la firma en el token y acepta o rechaza en consecuencia.

El codificador de ToolBox Hubs hace este cálculo usando la API Web Crypto integrada del navegador — las mismas primitivas criptográficas usadas por los navegadores para TLS. No se está haciendo en JavaScript hecho a mano o en una biblioteca de terceros sospechosa. Eso vale la pena saberlo.

Lo que HS256 no puede hacer

HS256 usa una clave simétrica — el mismo secreto que firma el token también lo verifica. Esto significa que cualquiera que pueda verificar tus tokens también puede crearlos. En un sistema donde un servidor emite tokens y otro los verifica, ambos servidores necesitan conocer el secreto. Compartir secretos entre servicios es un problema de coordinación y superficie de seguridad.

RS256 (y ES256) usan claves asimétricas. Una clave privada firma tokens — solo el servidor de auth la necesita, y nunca deja ese servidor. Una clave pública verifica tokens — esta puede distribuirse libremente, publicarse en un endpoint JWKS, ser cargada por cualquier servicio que necesite verificar tokens. Los servicios pueden verificar sin tener ninguna habilidad de acuñar.

Para cualquier cosa más compleja que un solo servicio backend, RS256 es usualmente la mejor elección arquitectónica. HS256 es más simple de configurar y está bien para sistemas más pequeños o escenarios donde controlas todos los validadores.

Las cosas de seguridad que vale la pena repetir

No pongas datos sensibles en JWTs. Hashes de contraseñas, números de tarjetas de crédito, PII que no necesita estar ahí — nada de eso. El payload es visible para cualquiera que tenga el token. Eso incluye al cliente, cualquier sistema de logging que capture headers de auth, y cualquier proxy o CDN entre medias. Trata el payload JWT como tratarías una cadena de consulta URL: asume que es visible.

Usa secretos de prueba con herramientas en línea. Incluso cuando una herramienta es genuinamente del lado del cliente y no envía tus datos a ninguna parte, el hábito de escribir secretos de producción en interfaces de navegador es malo. Crea un secreto de prueba. Usa test-secret-do-not-use-in-production como tu clave si quieres. Trata el secreto real como una contraseña: no deja el servidor donde vive.

Siempre establece una expiración. Un JWT sin exp es una credencial eterna. Si se filtra, tienes un problema hasta que rotes la clave de firma — lo que invalida todos los tokens existentes y cierra la sesión de todos. Tokens de corta duración más un flujo de refresh token es el patrón estándar por una razón.

Los ataques de confusión de algoritmo son reales. Algunas bibliotecas JWT tuvieron vulnerabilidades históricas donde podías cambiar el header alg a none y la biblioteca aceptaba tokens sin firmar. Siempre valida el algoritmo que tu servidor espera y rechaza cualquier otra cosa. No confíes en el header alg del token mismo.

ToolBox Hubs vs. jwt.io

jwt.io es la herramienta JWT canónica y la mayoría de los desarrolladores la conocen. Es buena. Pero hay dos razones por las que podrías preferir ToolBox Hubs:

Primero, ToolBox Hubs es explícitamente enfocado en privacidad y solo del lado del cliente. jwt.io ha recibido históricamente escrutinio sobre si los secretos escritos en él podrían ser registrados. No estoy diciendo que jwt.io sea malicioso — pero cuando el modelo de privacidad de una herramienta no está claramente documentado, el cálculo de riesgo cambia. Nuestra herramienta procesa todo en tu navegador.

Segundo, ToolBox Hubs se integra con herramientas relacionadas. Después de codificar un JWT, puedes saltar directamente al Decodificador JWT para inspeccionarlo, pasar el payload a través del Generador de Hash si necesitas hashear algún valor, o usar Cifrado/Descifrado de Texto si necesitas cifrado simétrico para algo que el payload JWT no debería llevar en texto plano.

Dicho esto: jwt.io tiene características que nosotros no tenemos, incluyendo selección de biblioteca y soporte RS256 con generación de pares de claves. Usa la herramienta correcta para lo que necesitas.

Un workflow práctico para desarrollo local

Así es como realmente uso un codificador JWT durante el desarrollo:

1. Decide qué claims necesita el token — usualmente sub, exp, y cualquier claim específico de la app que tu middleware verifique (como role u org_id).

2. Establece exp a algo lo suficientemente lejano en el futuro para que no expire durante una sesión de depuración. Yo usualmente hago tiempo Unix actual más 86400 (24 horas). El Convertidor de Timestamp ayuda con el cálculo mental.

3. Escribe un secreto de prueba memorable — algo obviamente falso como dev-secret-not-real.

4. Genera el token y pégalo en tu cliente API (Postman, curl, HTTPie, lo que sea).

5. Cuando algo va mal con la validación, pega el token en el Decodificador JWT para confirmar que el payload se ve bien, luego verifica que el secreto y algoritmo esperados de tu servidor coincidan con los que usaste para generarlo.

Este bucle resuelve el 90 % de la confusión de depuración relacionada con JWT. El 10 % restante es usualmente desviación de reloj (tu exp está desviado) o desajuste de algoritmo (generaste HS256, tu biblioteca espera RS256).

Lo que la herramienta no hará

Siendo honesto sobre las limitaciones:

Sin soporte RS256 o ES256. La firma con clave asimétrica no está disponible — necesitarías proporcionar una clave privada, y manejar eso en una UI de navegador añade complejidad. Para pruebas RS256, el paquete npm local jsonwebtoken o la biblioteca python-jose son más apropiados.

Sin revocación de tokens. Los JWTs son sin estado por diseño — una vez emitidos, son válidos hasta la expiración (asumiendo que la firma valida). No hay revocación incorporada. Si necesitas la habilidad de invalidar tokens específicos antes de que expiren, necesitas una blocklist de tokens en tu servidor. El codificador no puede ayudar con eso; es una preocupación arquitectónica.

Sin generación JWKS. Para sistemas basados en RS256, también querrías un endpoint JWKS (JSON Web Key Set). Eso está fuera del alcance de esta herramienta.

Para todo lo que está en el alcance — crear tokens firmados con HS256 para pruebas y depuración, entender la estructura JWT, mockear auth en desarrollo local — el Codificador JWT hace el trabajo sin ceremonia.

Empezando

Abre la herramienta Codificador JWT, escribe un payload simple como {"sub": "test-user", "role": "admin"}, establece un secreto de prueba, y presiona Generate. Mira la salida. Luego pégala en el Decodificador JWT y míralo descomponerse.

Una vez que has hecho eso una vez, la estructura JWT deja de ser abstracta. Sabes cuáles son las tres partes, sabes cómo se ve el JSON codificado en base64url, y sabes que la firma es solo un hash. Todo lo demás — integración de biblioteca, selección de algoritmo, validación de claims — se construye sobre esa base.

Herramientas relacionadas que vale la pena tener abiertas junto a esta: Decodificador JWT para inspeccionar tokens, Generador de Hash para entender lo que produce HMAC, y Cifrado/Descifrado de Texto para los casos donde el texto plano codificado en base64 realmente no es lo suficientemente bueno.