Decodificar un JWT no es verificarlo

Un JSON Web Token o JWT suele verse como tres cadenas separadas por puntos. Esa forma invita a una conclusión peligrosa: si un navegador puede decodificar las dos primeras cadenas, entonces su contenido será fiable. No lo es. Decodificar permite inspeccionar la estructura declarada de un token. Verificar es una decisión de seguridad de un sistema que conoce el emisor esperado, la audiencia, la política temporal, el algoritmo y la clave de verificación. Esta guía usa un ejemplo forjado y no productivo. No contiene una cuenta, secreto, clave privada ni credencial utilizable.

El problema

RFC 7519 define la serialización compacta de JWT como tres segmentos codificados en base64url: cabecera, payload y firma. Base64url es una codificación, no un cifrado. Cualquiera que posea el token puede leer los dos primeros segmentos y un atacante también puede escribir otros nuevos. El payload puede afirmar que un sujeto es administrador, que caduca el año próximo o que procede de un emisor familiar. Son afirmaciones aportadas por una entrada no confiable hasta que la verificación termina correctamente.

La diferencia importa allí donde un token modifica una autorización. Un panel de depuración puede decodificarlo localmente para mostrar una fecha o un claim mal formado. Ese panel no debe usar role, sub o scope para decidir qué puede hacer una persona. Del mismo modo, una interfaz puede mostrar un aviso de expiración, pero una API debe tomar su propia decisión y no aceptar la interpretación del navegador. Un token firmado puede ser válido para una aplicación y no aceptable para otra si la audiencia prevista es distinta.

Verificar no significa solo comprobar que hay tres partes. El verificador parte de una relación de confianza configurada. Acepta un conjunto reducido de algoritmos, obtiene una clave mediante un mecanismo controlado, verifica la firma sobre los datos protegidos originales y evalúa claims según una política local. RFC 8725 advierte que una aplicación no debe dejar que contenido controlado por un atacante elija comportamientos críticos de validación. Un decodificador no posee ese contexto.

Ejemplo práctico

Este es un token de demostración sintácticamente válido. La cabecera se decodifica como {"alg":"HS256","typ":"JWT"}. El payload se decodifica como {"sub":"demo-user","role":"admin","exp":1893456000,"iss":"https://issuer.example.invalid","aud":"demo-api"}. El último segmento es solo el texto base64url de la palabra “signature”; no se calculó con secreto alguno y no prueba nada. Está forjado de forma intencional.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZW1vLXVzZXIiLCJyb2xlIjoiYWRtaW4iLCJleHAiOjE4OTM0NTYwMDAsImlzcyI6Imh0dHBzOi8vaXNzdWVyLmV4YW1wbGUuaW52YWxpZCIsImF1ZCI6ImRlbW8tYXBpIn0.c2lnbmF0dXJl

Un decodificador puede separar el texto por puntos, aplicar base64url a los dos primeros segmentos e imprimir campos. exp es una NumericDate, segundos desde el origen Unix, por lo que puede convertirse a fecha para inspección. iss es el identificador que el token afirma como emisor. aud identifica al destinatario o destinatarios previstos. Ver valores plausibles no demuestra que el emisor los creó, que la API actual es destinataria ni que el token sea aceptable ahora.

Si se cambia demo-user por otro sujeto o role de viewer a admin y se vuelve a codificar el payload, el resultado seguirá teniendo tres segmentos bien formados y se decodificará sin error. Un verificador correcto lo rechaza porque la firma deja de coincidir con cabecera y payload bajo la clave esperada. El ejemplo hace visible el problema: el análisis sintáctico funciona sin que exista confianza.

Procedimiento

Empieza tratando un token como dato operativo sensible aunque no sea una contraseña. No pegues un bearer token de producción en un sitio no aprobado, ticket, chat o captura. Para diagnosticar localmente, usa un token de desarrollo controlado, oculta identificadores o inspecciónalo en el entorno que lo emitió. Conserva solo los datos mínimos para reproducir el problema: nombres y tipos de claims y una conversión de expiración.

Para inspeccionar, comprueba primero que la forma compacta tenga exactamente tres segmentos no vacíos. Decodifica cabecera y payload como JSON UTF-8 sin concederles autoridad. Anota alg, pero no permitas que el servidor el use para seleccionar su política. Comprueba el formato numérico de exp, nbf e iat; compara iss con el emisor esperado; y compara aud con el identificador del recurso receptor. Son observaciones de diagnóstico, no un resultado de aprobación.

Para autenticación o autorización, entrega el token compacto original a un verificador de confianza. Debe contar con una lista explícita de algoritmos y tipos de clave aceptados, un emisor configurado y una audiencia configurada. Verifica la firma antes de depender del payload, rechaza expirados según su política de reloj y aplica controles de nbf, tipo de token, sujeto o autorización específica. El descubrimiento de claves también debe autenticarse y limitarse al emisor conocido; no es seguro descargar una ubicación de claves anunciada por una cabecera no confiable.

Después separa validación de identidad y autorización de la aplicación. Un token verificado puede establecer quién emitió un claim, pero la aplicación aún decide si ese sujeto puede realizar una acción. Aplica mínimo privilegio, reglas de autorización del servidor y comprobaciones del recurso después de verificar. Registra resultados sin guardar bearer tokens completos. Ante un fallo, devuelve una respuesta genérica y conserva diagnósticos detallados solo en registros operativos protegidos.

Explicación técnica

La firma se calcula sobre la cabecera y el payload codificados, no sobre el objeto JSON después de que un decodificador lo reformatee. Así un verificador no acepta silenciosamente espacios, campos reordenados o segmentos sustituidos. En algoritmos simétricos emisor y verificador comparten un secreto; en asimétricos el emisor firma con clave privada y el verificador usa una clave pública autenticada. En ambos casos, poder leer un payload no tiene relación con autoridad para firmarlo.

Los claims son contextuales. RFC 7519 define nombres registrados, pero deja la política a cada destinatario. exp marca un momento tras el cual no debe aceptarse el token, pero el sistema decide el desfase de reloj permitido. nbf indica inicio de validez. iss requiere una comparación exacta con un identificador configurado, no una similitud visual. aud puede ser cadena o lista, y una API debe exigir estar entre los destinatarios. Un claim puede ser sintácticamente correcto y aun así ser incorrecto para la petición actual.

La confusión de algoritmos explica por qué se configura en lugar de inferir. Un servicio que acepta el alg anunciado por la entrada puede ser inducido a usar una ruta de verificación inapropiada. Si mezcla emisores sin asociar claves, audiencias y algoritmos, puede aceptar un token de otro dominio. RFC 8725 recomienda reglas mutuamente excluyentes para tipos distintos de JWT y verificación estricta del algoritmo. Son responsabilidades del servidor; un decodificador genérico no puede conocerlas.

Errores frecuentes

Un fallo habitual es tratar el payload decodificado como una sesión. Por ejemplo, un cliente lee role: admin y muestra una ruta privilegiada antes de que el backend verifique el token. Ocultar un botón no autoriza, pero puede confundir y revelar comportamiento. Cada operación protegida debe exigir autorización en el lado de confianza. Otro fallo es aceptar exp solo porque está en el futuro: una fecha futura no arregla firma, emisor, audiencia o tipo de token inválidos.

También es un error registrar tokens completos al diagnosticar una decodificación. Los bearer tokens pueden conceder acceso hasta caducar, por lo que registros, analítica, informes de error y extensiones del navegador se convierten en exposición innecesaria. Redáctalos y no los copies en ejemplos. Un decodificador público puede servir para mirar formato, pero no conoce claves privadas, emisores aprobados, revocación ni la API exacta receptora.

No desactives la validación de firma para que una prueba funcione. Crea un emisor y claves de prueba separados, con vida corta y permisos limitados. Rechaza tokens sin firma salvo que un formato cuidadosamente diseñado y no autenticador los exija; una biblioteca no debe aceptar una degradación de algoritmo porque una cabecera lo pidió. Prueba firmas alteradas, audiencias inesperadas, tiempos antiguos y emisores erróneos con la misma atención que el caso correcto.

Consideraciones

Define límites de token antes de elegir biblioteca. Documenta quién emite, qué servicios verifican, qué audiencias existen y cómo rotan las claves. Usa audiencias distintas para APIs con privilegios distintos. Configura el URI del emisor de forma exacta y valídalo de manera consistente. Si hay perfiles de token diferentes, da a cada uno una regla de validación separada en lugar de una regla permisiva que intente adivinar su finalidad desde claims opcionales.

El tiempo requiere cuidado operativo. Sincroniza relojes de servidor, decide un desfase pequeño y documentado y observa fallos que indiquen deriva. Mantén vidas de access token proporcionales al riesgo y diseña renovación o revocación fuera del decodificador. Mostrar exp localmente ayuda a explicar un fallo, pero solo la política temporal del verificador decide aceptación. No supongas que un token es válido porque la fecha visible parece reciente en otra zona horaria.

Evita conservar datos decodificados en estado de cliente innecesario. Una interfaz puede necesitar información no sensible, pero el servidor debe ser autoridad para permisos y recursos protegidos. Si un navegador almacena un bearer token, su exposición depende del modelo de amenazas y del almacenamiento; decodificarlo no la reduce. Una guía breve no elige la arquitectura correcta: solicita revisión de seguridad al diseñar un límite de identidad.

Limitaciones

Esta guía explica el límite conceptual entre decodificar y verificar. No ofrece una configuración lista de autenticación, un diseño de gestión de claves ni garantiza que una biblioteca JWT sea segura si se configura mal. APIs de bibliotecas, distribución de claves, perfiles de token, almacenamiento en navegador y requisitos de incidentes varían por sistema. Lee la documentación actual del verificador y pruébalo con los ajustes reales de emisor y audiencia.

JWT no es obligatorio para todas las sesiones o APIs. Tokens opacos, sesiones de servidor y otros mecanismos tienen compensaciones distintas. Una firma válida tampoco prueba que un usuario esté autorizado para toda acción, que un dispositivo esté íntegro o que un token no haya sido revocado externamente. Trata la verificación como un control necesario dentro de un diseño más amplio.

Lista de comprobación

Antes de confiar en un JWT, conserva el token compacto original y separa inspección de autorización. Decodifica cabecera y payload solo para diagnosticar estructura; nunca tomes claims visibles como prueba. Verifica firma en un sistema de confianza con lista de algoritmos y origen de claves autenticado. Exige emisor y audiencia esperados, evalúa expiración y not-before con política temporal documentada y aplica autorización de servidor después. Nunca publiques o registres bearer tokens reales, nunca desactives la verificación por comodidad y prueba como negativos firmas y claims modificados. Consulta RFC 7519 y RFC 8725 junto con la documentación actual de tu biblioteca.