Crear un JSON Web Token (JWT) firmado

¿Qué es JWT Builder?

JWT Builder es una herramienta en línea que produce un JSON Web Token firmado (JWT) a partir de un payload JSON y un secreto HMAC. Está dirigida a los desarrolladores que necesitan generar rápidamente un token de prueba para verificar el comportamiento de una API, simular una sesión autenticada en Postman, o reproducir un bug ligado a la expiración o al alcance de un token.

Al contrario que nuestro JWT decoder, que se limita a leer un token existente, JWT Builder fabrica un token completo: construye el header, codifica el payload, calcula la firma HMAC y ensambla el conjunto en el formato compacto header.payload.signature esperado por todas las bibliotecas JWT del mercado.

¿Por qué generar un JWT?

Un builder de JWT no tiene vocación de emitir tokens de producción. Es ante todo una herramienta de desarrollo y pruebas. Estos son los escenarios más habituales:

• Pruebas de integración: producir JWT previsibles para pilotar pruebas E2E que golpean endpoints protegidos sin depender del verdadero proveedor de identidad.
• Mocks de API: sustituir temporalmente una llamada al IdP por un JWT firmado localmente con el mismo secreto de prueba.
• Desarrollo local: conectarse a su propio backend generando a mano un token que contenga las claims deseadas, sin tener que pasar por todo el flow OAuth2.
• Demostraciones: ilustrar un recorrido de autenticación o un workflow basado en permisos sin tener un IdP real a mano.
• Reproducción de bugs: forjar un token caducado, un token con un aud incorrecto, un token sin algunas claims, para probar las rutas de error de su API.
• Depuración de un parser personalizado: inyectar JWT especialmente construidos para probar un parser hecho a mano.

Composición de un JWT

Un JWT firmado se compone de tres segmentos separados por un punto, cada uno codificado en Base64URL (variante de Base64 sin padding y con -/_ en lugar de +//):

• Header: un objeto JSON que describe el algoritmo de firma y el tipo del token, por ejemplo {"alg":"HS256","typ":"JWT"}. JWT Builder lo genera automáticamente a partir del algoritmo que elija.
• Payload: un objeto JSON arbitrario que contiene las claims del token (sujeto, permisos, fechas de expiración). Es la parte que aporta usted.
• Firma: un HMAC-SHA calculado sobre la concatenación base64url(header) + "." + base64url(payload) con su clave secreta. Es la que garantiza la integridad del token.

Casos de uso en detalle

• API mock para pruebas E2E: su suite Cypress o Playwright debe llamar a una API que exige un Authorization: Bearer .... En lugar de orquestar un login completo en cada prueba, se firma un JWT al vuelo con el secreto compartido y se inyecta en la cabecera.
• Demostración de SSO: presentar un recorrido de autenticación federada sin depender de un IdP en línea.
• Fixture de prueba: generar un JWT determinista a partir de un payload conocido para servir de fixture estable en pruebas unitarias.
• Diagnóstico de un parser personalizado: probar un parser JWT propio con tokens deliberadamente mínimos o deliberadamente extraños (claims que faltan, tipos inesperados).
• Aprendizaje: entender concretamente cómo se construye un JWT, modificando el payload y observando cómo cambia la firma.

Algoritmos admitidos: HS256, HS384, HS512

Nuestra herramienta admite los tres algoritmos HMAC estándar de la especificación JWT (RFC 7519):

• HS256: HMAC con SHA-256. Firma de 32 octetos. El más utilizado en la práctica, buen compromiso entre rapidez y solidez criptográfica. Recomendado por defecto.
• HS384: HMAC con SHA-384. Firma de 48 octetos. Adaptado a contextos que exigen un margen de seguridad superior.
• HS512: HMAC con SHA-512. Firma de 64 octetos. El más robusto, a costa de un token ligeramente más voluminoso.

¿HMAC o RSA?

Los algoritmos HS* son simétricos: la misma clave sirve para firmar y verificar. Es sencillo y rápido, pero significa que cualquier servicio capaz de verificar un token también es capaz de emitirlo. Si necesita separar esos dos roles (un único emisor, varios consumidores), recurra a los algoritmos RS256/RS384/RS512 (RSA, asimétricos), que puede verificar con nuestro JWT verifier.

Seguridad: proteger su secreto

La seguridad de un JWT firmado en HMAC reposa enteramente sobre la confidencialidad del secreto. Algunas reglas básicas:

• Utilice un secreto largo y aleatorio. La RFC 7518 recomienda como mínimo el tamaño de la salida del algoritmo (32 octetos para HS256, 48 para HS384, 64 para HS512). Una contraseña humana como azerty123 es trivialmente atacable mediante fuerza bruta offline.
• No firme nunca un JWT en el lado del cliente. El secreto acabaría en el código JavaScript distribuido al navegador, expuesto a cualquier usuario. La firma debe permanecer siempre en el lado del servidor.
• Almacene el secreto en una variable de entorno (p. ej. JWT_SECRET), nunca en un repositorio Git. Considere usar un vault como HashiCorp Vault, AWS Secrets Manager o los Symfony Secrets según su stack.
• Rote el secreto con regularidad (key rotation), sobre todo tras cualquier incidente o salida de una persona que haya tenido acceso a la configuración.
• JWT Builder está destinado a pruebas y aprendizaje. Para producción, utilice la biblioteca JWT de su framework (lcobucci/jwt, firebase/php-jwt, jose-php).

Buenas prácticas de claims

El payload es un objeto JSON libre, pero la RFC 7519 define un conjunto de registered claims que las bibliotecas JWT saben interpretar. Incluir las claims correctas hace que su token sea portable y evita bugs sutiles:

• iss (issuer): identificador del emisor, por ejemplo "https://api.example.com".
• sub (subject): identificador de la persona o entidad implicada, a menudo el ID de usuario.
• aud (audience): para quién va destinado el token, para impedir la reutilización de un token en otra API.
• exp (expiration time): timestamp Unix tras el cual el token deja de ser válido. Inclúyalo siempre, incluso para un token de prueba: un token sin expiración es un mal hábito difícil de corregir después.
• nbf (not before): timestamp antes del cual el token aún no es válido. Útil para preemitir un token activable más tarde.
• iat (issued at): timestamp de emisión, útil para registrar y revocar.
• jti (JWT ID): identificador único del token, indispensable para la idempotencia y para implementar una lista de revocación.

Ejemplo de payload típico

{
  "iss": "https://api.example.com",
  "sub": "user-12345",
  "aud": "mobile-app",
  "iat": 1714723200,
  "exp": 1714726800,
  "jti": "9f2d6b1e-2c4a-4f8a-9c3a-87a2b8a4b7e1",
  "scope": "read:profile write:profile"
}

Cómo utilizar la herramienta

1. Introduzca el payload como JSON válido. Es un objeto, así que empieza por { y termina por }.
2. Indique el secreto HMAC. Elija una cadena larga y aleatoria para los tokens de producción.
3. Seleccione el algoritmo: HS256 por defecto, HS384 o HS512 según sus necesidades.
4. Haga clic en crear. El JWT firmado aparece, listo para pegar en una cabecera Authorization: Bearer ....
5. A continuación puede verificar el token con el mismo secreto para confirmar la coherencia del round-trip, o decodificarlo para releer su contenido.

Preguntas frecuentes

Ejemplo de solicitud

curl -X POST https://cdrn.fr/api/v1/tools/jwt-builder/execute \
  -H "Content-Type: application/json" \
  -d '{"payload":"...","secret":"...","algorithm":"HS256"}'

Esquema de entrada

Puntos de acceso

• GET https://cdrn.fr/api/v1/tools - lista todas las herramientas disponibles
• GET https://cdrn.fr/api/v1/tools/jwt-builder - recupera el esquema de esta herramienta
• POST https://cdrn.fr/api/v1/tools/jwt-builder/execute - ejecuta esta herramienta con un payload JSON