Después de iniciar sesión, ¿cómo sabe un servidor que cada solicitud posterior realmente proviene de usted? Una respuesta popular es un Token web JSON, o JWT, que generalmente se pronuncia “jota”. Es un pequeño dato firmado que el cliente envía con cada solicitud y el servidor puede verificarlo sin tocar una base de datos.

La forma más rápida de entender un JWT es construir uno y luego intentar romperlo. Lo hicimos usando solo la biblioteca estándar de Python, en Python 3.13, y el resultado a continuación proviene de esa ejecución. Este código es para aprender. En una aplicación real, utilice una biblioteca bien mantenida, porque es fácil equivocarse en los detalles de verificación.

¿Qué es un JWT?

JWT es un estándar abierto, definido en RFC 7519, para transmitir reclamaciones entre dos partes como una cadena compacta. Un reclamo es simplemente una declaración, como “el ID de este usuario es 42”. Como el token está firmado, el receptor puede confirmar quién lo emitió y que nadie lo ha alterado.

Piense en una pulsera de festival. El personal en la puerta revisa tu boleto una vez y te entrega una banda que es difícil de falsificar. Después de eso, cada puesto sólo mira a la banda, sin necesidad de llamar a la taquilla. Un JWT funciona de forma muy similar a una API.

Cómo funciona el inicio de sesión de JWT

1. El usuario envía un nombre de usuario y contraseña al punto final de inicio de sesión.
2. El servidor los verifica y crea un token firmado.
3. El cliente almacena el token.
4. Cada solicitud posterior lo incluye, normalmente en un encabezado: Authorization: Bearer <token>.
5. El servidor verifica la firma y la caducidad, luego lee las reclamaciones.

El principal beneficio está en el paso 5. El servidor no tiene que buscar una sesión, lo cual resulta conveniente cuando muchos servicios o servidores necesitan verificar el mismo token. Si es nuevo en las API, comience con qué es una API.

Las tres partes de un JWT

Un JWT parece texto aleatorio, pero consta de tres secciones codificadas en Base64URL separadas por puntos. Aquí hay uno que generamos:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiI0MiIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzkzNTAwMDAwLCJleHAiOjE3OTM1MDA5MDB9
.7YfUDH_T-iDh8bMmUT8mmKYwOstzT8Ty--DTTAmQGWM

Hemos agregado saltos de línea para que sea más fácil de leer. Al decodificar las dos primeras partes se obtiene JSON simple:

Header:  {"alg":"HS256","typ":"JWT"}
Payload: {"sub":"42","role":"user","iat":1793500000,"exp":1793500900}

Reclamaciones estándar

También puede agregar reclamos personalizados, como role. Los tiempos son marcas de tiempo de Unix, en segundos. Mantenga la carga útil pequeña, ya que el token viaja con cada solicitud.

Construye uno tú mismo

Crear un token implica codificar las dos partes JSON y luego firmarlas con un secreto usando HMAC-SHA256:

import base64, hashlib, hmac, json

SECRET = b"demo-secret-do-not-use-in-production"

def b64url(data):
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()

def sign(message):
    return b64url(hmac.new(SECRET, message.encode(), hashlib.sha256).digest())

def create_token(payload):
    header = {"alg": "HS256", "typ": "JWT"}
    parts = [
        b64url(json.dumps(header, separators=(",", ":")).encode()),
        b64url(json.dumps(payload, separators=(",", ":")).encode()),
    ]
    message = ".".join(parts)
    return message + "." + sign(message)

La verificación funciona recalculando la firma y comparándola con la del token. Sólo alguien con el secreto puede producir uno que coincida:

def verify_token(token, now):
    header, payload, signature = token.split(".")
    expected = sign(header + "." + payload)
    if not hmac.compare_digest(signature, expected):
        raise ValueError("bad signature")
    claims = json.loads(b64url_decode(payload))
    if claims["exp"] < now:
        raise ValueError("token expired")
    return claims

Un token válido devolvió sus reclamos como se esperaba. compare_digest se utiliza ya que se ejecuta en tiempo constante, lo que evita la fuga de información por diferencias de tiempo.

Intenta manipularlo

Supongamos que un atacante decodifica la carga útil, cambia "role":"user" a "role":"admin", la codifica nuevamente y conserva la firma anterior. Probamos esto, junto con otros dos ataques:

Ese último intento apunta a una verdadera debilidad histórica. Algunas bibliotecas alguna vez confiaron en el propio encabezado del token, por lo que un atacante podría simplemente declarar que no se necesitaba firma. Nuestro código siempre utiliza un algoritmo fijo, por eso fue rechazado. En una biblioteca real, especifique siempre los algoritmos que acepta.

Firmado, no cifrado

Este es el punto más incomprendido sobre los JWT. Nuestro token falsificado fue rechazado, pero su contenido aún era perfectamente legible:

{"sub":"42","role":"admin","iat":1793500000,"exp":1793500900}

Base64URL es una codificación, no una encriptación, y cualquiera puede revertirla sin ninguna clave. La firma impide que las personas cambien los datos, pero no lean. Por lo tanto, nunca coloque contraseñas, números de tarjetas o datos personales privados en una carga útil de JWT. Si el contenido debe ocultarse, utilice tokens cifrados (JWE) o simplemente mantenga los datos en el servidor.

HS256 frente a RS256

Con la firma asimétrica, otros servicios pueden verificar tokens sin poder acuñar los suyos propios, lo que limita el daño si uno se ve comprometido.

JWT frente a sesiones

Los JWT a menudo se presentan como un reemplazo moderno de las sesiones. En realidad, cada uno tiene sus ventajas y desventajas:

Para un sitio web tradicional generado por un servidor, una cookie de sesión suele ser más sencilla y segura. Los JWT tienden a tener más sentido para las API consumidas por varios servicios o para clientes móviles.

Dónde almacenar tokens en un navegador

Muchas guías de seguridad favorecen las cookies HttpOnly, Secure, SameSite para aplicaciones web. Cualquiera que elijas, utiliza siempre HTTPS. Para enviar un token desde JavaScript, consulte nuestro tutorial de JavaScript Fetch API.

Actualizar fichas

El vencimiento corto limita el daño de un token robado, pero nadie quiere iniciar sesión cada 15 minutos. La solución habitual utiliza dos tokens:

• Token de acceso: de corta duración, como minutos, y se envía con cada solicitud de API.
• Token de actualización: tiene una vida más larga, se almacena con más cuidado y se usa solo para obtener nuevos tokens de acceso.

El servidor realiza un seguimiento de los tokens de actualización, por lo que puede revocarlos, lo que le brinda un cierre de sesión práctico. Rotarlos en cada uso también le ayuda a detectar robos, porque una ficha antigua robada se vuelve a reproducir.

Errores de seguridad comunes

• Decodificar sin verificar. Leer una carga útil no la hace confiable. Comprueba siempre la firma.
• Aceptar cualquier algoritmo. Establecer una lista explícita de algoritmos permitidos.
• Usar un secreto débil. Los secretos breves se pueden descifrar sin conexión. Utilice un valor aleatorio largo y manténgalo fuera del control de fuente.
• Omitiendo el vencimiento. Los tokens sin exp pueden funcionar para siempre si son robados.
• No marcar iss y aud. De lo contrario, un token emitido para un servicio puede ser aceptado por otro.
• Confiar en afirmaciones obsoletas. Una función dentro de un token puede estar desactualizada hasta que caduque.
• Tokens de registro. Cualquiera que lea sus registros podría reutilizarlos.
• No probar rutas de falla. Agregue pruebas para tokens vencidos y modificados, así como también válidos. Nuestra guía Pruebas de API con Postman puede resultar útil.

Conclusión

Un JWT son datos firmados en los que un servidor puede confiar sin una búsqueda, no un contenedor secreto ni una actualización automática a lo largo de las sesiones. Utilice una caducidad corta, verifique todo con una biblioteca mantenida y mantenga los datos privados fuera de la carga útil. Para comprobarlo usted mismo, ejecute un pequeño script como el nuestro, cambie un carácter de un token y observe cómo falla la verificación.

Preguntas frecuentes

sigue aprendiendo