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

PublicadoHerramientaGenerador y verificador de JWT

Contenido
  1. Ves que la verificación falla, pero no sabes por qué
  2. Cómo verificar la firma calculándola tú mismo, sin herramientas
  3. Los dos motivos de un fallo de verificación, y la confusión entre codificación y cifrado
  4. En resumen
  5. Preguntas frecuentes

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.

Generador y verificador de JWT

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.

CausaQué es lo que difiereCómo comprobarlo
Clave secreta distintaLa propia clave usada para calcular la firma no es la misma que en el momento de la emisiónVolver a contrastar si es exactamente la misma cadena que usa el servidor emisor (incluidos espacios y saltos de línea)
Contenido alteradoLos valores JSON del header o del payload han cambiado después de la emisiónSi 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.

AspectoCodificación Base64Url (payload del JWT)Cifrado
FinalidadTrasladar los datos a textoOcultar el contenido para que terceros no puedan leerlo
¿Se necesita una clave para restaurarlo?NoSí
Alcance de la restauración del originalCualquiera, solo con la cadena del tokenSolo 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.
Generador y verificador de JWT

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

Artículos relacionados

  1. line-clamp CSS: cómo usarlo y por qué no funcionaEntiende por qué line-clamp no funciona sin display: -webkit-box y qué propiedades necesita el truncado de una línea y de varias líneas.
  2. Cómo convertir listas y viñetas a Markdown, HTML o símbolosAprende a cambiar viñetas y números por listas Markdown, etiquetas HTML ul/li o símbolos personalizados, con los errores más comunes al copiar y pegar.
  3. Diferencia entre localStorage y sessionStorage: cómo comprobarlaAprende en qué se diferencian localStorage y sessionStorage, cómo ver sus valores desde las DevTools y por qué salta el error QuotaExceededError.
  4. Cuántas hojas de wongoji necesitas: cálculo por líneasPor qué dividir el número de caracteres entre 200 no da la cantidad de hojas: los saltos de línea y la sangría cambian el cálculo.
  5. Conversión de Markdown a HTML: reglas y CSS de estilosDescubre qué etiqueta HTML genera cada símbolo de Markdown y cómo dar estilo al resultado con CSS para que se lea bien.
  6. Convertir tablas Markdown a HTML y JSON: reglas y límitesDescubre cómo se corresponden las tablas Markdown, las etiquetas HTML table y los arrays JSON, y qué pasa cuando faltan columnas o el guion separador.

Herramientas relacionadas