Verificar un JWT: cómo comprobar si la firma fue alterada

Contenido
Verificar la firma de un JWT te permite comprobar si el token conserva exactamente el contenido que tenía cuando se emitió y si esa firma se creó realmente con la clave secreta que tú conoces. Este artículo está pensado para desarrolladores que quieren comprobar por su cuenta si un token recibido en la respuesta de una API ha sido alterado.
Aquí explicamos cómo se calcula y se compara la firma, y los dos motivos distintos por los que aparece un "fallo de verificación", tal como ocurre en el funcionamiento real del código.
Resumen ① Un JWT es una cadena formada por tres partes, header.payload.signature, unidas por puntos; el header y el payload no están cifrados, solo están codificados en Base64Url. ② La signature es el resultado de calcular HMAC-SHA256 con la clave secreta sobre la cadena formada por header y payload, y verificar consiste en repetir ese mismo cálculo y comparar si el valor coincide. ③ Un fallo de verificación aparece exactamente igual tanto si la clave secreta es distinta como si el contenido ha sido alterado, y el mensaje de error por sí solo no permite distinguir cuál de los dos casos es.
Ves que la verificación falla, pero no sabes por qué
Es muy habitual que una API de backend emita un JWT al iniciar sesión y que, en cada petición posterior, el cliente envíe ese token en la cabecera Authorization. El servidor recalcula la firma del token en cada petición para comprobar que realmente lo emitió él.
El problema llega en el momento en que esa verificación devuelve un "fallo". Si al volver a desplegar el servidor cambió la clave secreta de las variables de entorno, o si en el entorno de pruebas se introdujo por error otra clave, en pantalla aparece únicamente un "fallo", exactamente igual que con un token alterado. Si no entiendes el mecanismo, acabas buscando la causa donde no está.
Otro malentendido frecuente es pensar que "la información del usuario que va en el payload está cifrada, así que está a salvo". En realidad el payload solo está codificado en Base64Url, de modo que cualquiera que tenga la cadena del token puede leer su contenido.
Este malentendido lleva a veces a cometer el error de incluir en el payload datos sensibles como contraseñas o números de identificación.
Cómo verificar la firma calculándola tú mismo, sin herramientas
Un JWT consta de tres partes unidas por puntos (.). El orden es header.payload.signature, y cada parte contiene lo siguiente.
- header: un JSON con el algoritmo de firma (alg) y el tipo de token (typ)
- payload: un JSON con los datos (claims) que realmente quieres incluir
- signature: el valor resultante de firmar con la clave secreta la cadena formada por header y payload
El header y el payload son, cada uno, un JSON codificado en Base64Url. Como se trata de una codificación y no de un cifrado, cualquiera puede recuperar el JSON original sin ninguna clave.
Por ejemplo, la parte header de un token HS256, eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9, se decodifica así.
{"alg":"HS256","typ":"JWT"}
Base64Url se diferencia del Base64 estándar en dos caracteres. + pasa a ser - y / pasa a ser _, y el relleno = del final se omite. Para usar un decodificador base64 estándar hay que revertir esos dos caracteres y añadir el relleno.
El procedimiento para verificar la signature es el siguiente. Primero vuelves a unir la parte header y la parte payload del token con un punto para formar la cadena header.payload.
Si calculas HMAC-SHA256 sobre esa cadena con la misma clave secreta que se usó al emitirla y luego lo codificas en Base64Url, el resultado debe coincidir exactamente con la tercera parte del token.
printf '%s' "$HEADER.$PAYLOAD" | openssl dgst -sha256 -hmac "시크릿키" -binary | openssl base64
Este cálculo es determinista. Con la misma cadena y la misma clave se obtiene siempre la misma firma.
Si cambias una sola letra del header o del payload, la firma recalculada será un valor completamente distinto y ya no coincidirá con la original. Eso de "detectar alteraciones" se reduce, en la práctica, a esta única comparación.
Hacerlo a mano propicia errores en la sustitución de caracteres entre Base64 y Base64Url, en la restauración del relleno omitido y en la sintaxis del comando HMAC. Además, repetir este proceso cada vez resulta engorroso.
Compruébalo con nuestra herramienta.
Calcula y compara la firma al instante en el navegador. La clave secreta y el token que introduces no se envían al servidor.

Los dos motivos de un fallo de verificación, y la confusión entre codificación y cifrado
Detrás de un único resultado de "fallo de verificación" hay dos causas distintas que se superponen. Si la firma recalculada no coincide con la del token, se muestra siempre "fallo", independientemente del motivo.
| Causa | Qué es lo que difiere | Cómo comprobarlo |
|---|---|---|
| Clave secreta distinta | La propia clave usada para calcular la firma no es la misma que en el momento de la emisión | Volver a contrastar si es exactamente la misma cadena que usa el servidor emisor (incluidos espacios y saltos de línea) |
| Contenido alterado | Los valores JSON del header o del payload han cambiado después de la emisión | Si falla aun habiendo introducido la misma clave que al emitir, el problema está en el contenido modificado |
Es decir, el mensaje de fallo de verificación en sí no distingue entre las dos causas. Si tienes la certeza de que la clave es la correcta y aun así falla, entonces sí puedes acotar que "el contenido ha cambiado".
La segunda confusión es creer que "el payload está cifrado". Codificar y cifrar tienen finalidades completamente distintas.
| Aspecto | Codificación Base64Url (payload del JWT) | Cifrado |
|---|---|---|
| Finalidad | Trasladar los datos a texto | Ocultar el contenido para que terceros no puedan leerlo |
| ¿Se necesita una clave para restaurarlo? | No | Sí |
| Alcance de la restauración del original | Cualquiera, solo con la cadena del token | Solo quien tenga la clave de descifrado correcta |
Lo que garantiza la firma (signature) es la integridad (que no ha cambiado desde la emisión) y la autenticación del emisor (que lo creó quien conoce esa clave secreta). No garantiza la confidencialidad (ocultar el contenido).
Los valores incluidos en el payload puede decodificarlos y leerlos cualquiera que tenga el token, independientemente de si la firma es válida o no.
En resumen
- Un JWT es una cadena formada por tres partes, header.payload.signature, unidas por puntos.
- El header y el payload son solo codificación Base64Url, así que cualquiera puede decodificarlos y leerlos. No están cifrados.
- La signature es el resultado de calcular HMAC-SHA256 con la clave secreta sobre la cadena header.payload, y verificar consiste en repetir ese cálculo y comparar si el valor coincide.
- Un "fallo de verificación" aparece igual tanto si la clave secreta es distinta como si el contenido ha sido alterado, y el mensaje por sí solo no permite distinguirlo.
- La firma sirve para la integridad y para confirmar al emisor, no para ocultar el contenido del payload.
Calcula y compara la firma al instante en el navegador. La clave secreta y el token que introduces no se envían al servidor.
Preguntas frecuentes
¿Puedo ver el payload de un JWT sin cifrarlo?
Con solo decodificarlo puedes ver el contenido. El header y el payload están codificados en Base64Url, así que cualquiera puede recuperar el JSON original sin ninguna clave. La pestaña de verificación de esta herramienta también muestra siempre el JSON decodificado, independientemente de si la firma es correcta.
Si la verificación falla, ¿significa siempre que el token está falsificado?
No. Si la clave secreta usada para verificar no es la misma que la del momento de la emisión, también aparece un fallo exactamente igual. Si has introducido exactamente la misma cadena que usa el servidor emisor y aun así falla, entonces es el momento de considerar la posibilidad de que el contenido haya cambiado.
¿Puedo verificar tokens firmados con algoritmos de clave asimétrica como RSA?
Esta herramienta solo admite firmas con clave simétrica HMAC-SHA256 (HS256). Los tokens firmados con algoritmos de clave asimétrica como RSA (RS256, etc.) no se pueden verificar con esta herramienta.
¿La clave secreta o el token que introduzco en esta herramienta se envían a un servidor?
No se envían. La generación y la verificación de firmas se calculan únicamente en tu dispositivo mediante la Web Crypto API del navegador, y los valores introducidos no salen al exterior.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano