Autenticación con JWT

Teoría22 min20 XP

Una API real no puede dejar que cualquiera vea o modifique los datos: necesita saber QUIÉN hace cada petición y qué tiene permitido. Eso es la AUTENTICACIÓN. El mecanismo estándar en APIs modernas son los JWT (JSON Web Tokens): tras iniciar sesión, el usuario recibe un "pase" firmado que envía en cada petición, y la API lo verifica. Hoy entiendes cómo proteger tu API con login, tokens y endpoints protegidos —la seguridad que ninguna API de producción puede omitir—.

El brazalete del evento

El flujo y el hasheo de contraseñas

El flujo de JWT tiene tres momentos, y una regla de oro sobre las contraseñas:

auth.py

from passlib.context import CryptContext
from datetime import datetime, timedelta, timezone
import jwt   # pip install pyjwt

# --- Contraseñas: NUNCA en texto plano. Se guardan HASHEADAS ---
pwd = CryptContext(schemes=["bcrypt"])

hash_guardado = pwd.hash("mi_clave_secreta")   # esto es lo que se guarda en la BD
print(pwd.verify("mi_clave_secreta", hash_guardado))   # True  -> verificar en login
print(pwd.verify("clave_mala", hash_guardado))         # False

# --- Crear un token JWT tras un login exitoso ---
SECRET = "clave-secreta-del-servidor"   # en producción: variable de entorno

def crear_token(usuario_id: int) -> str:
  payload = {
      "sub": str(usuario_id),                                    # a quién pertenece
      "exp": datetime.now(timezone.utc) + timedelta(hours=1),    # cuándo expira
  }
  return jwt.encode(payload, SECRET, algorithm="HS256")

# --- Verificar un token (en cada petición protegida) ---
def verificar_token(token: str) -> int:
  datos = jwt.decode(token, SECRET, algorithms=["HS256"])   # falla si es inválido/expirado
  return int(datos["sub"])

La regla ABSOLUTA: las contraseñas NUNCA se guardan en texto plano —se guardan HASHEADAS (con bcrypt u otro), un proceso irreversible—. En el login, comparas el hash de lo que escribió el usuario con el guardado (pwd.verify), sin nunca almacenar la clave real. Si coincide, creas un TOKEN JWT (jwt.encode) que incluye quién es el usuario (sub) y cuándo expira (exp), firmado con una clave secreta del servidor. El token viaja al cliente, que lo guarda y lo envía en cada petición. La API lo VERIFICA (jwt.decode): si la firma es válida y no expiró, confía en su contenido —sabe quién es sin consultar la base de datos—.

Proteger endpoints en FastAPI

Dependencias que exigen autenticación

FastAPI protege endpoints con DEPENDENCIAS: funciones que se ejecutan antes del endpoint y pueden exigir un token válido:

protegido.py

from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()
oauth2 = OAuth2PasswordBearer(tokenUrl="login")

# esta dependencia extrae y verifica el token; da el usuario o rechaza
def usuario_actual(token: str = Depends(oauth2)) -> int:
  try:
      return verificar_token(token)
  except Exception:
      raise HTTPException(status_code=401, detail="Token inválido o expirado")

# ENDPOINT PÚBLICO: login (devuelve el token)
@app.post("/login")
def login(usuario: str, clave: str):
  # ... verificar usuario y clave contra la BD ...
  return {"access_token": crear_token(usuario_id=1), "token_type": "bearer"}

# ENDPOINT PROTEGIDO: solo con token válido (la dependencia lo exige)
@app.get("/mis-gastos")
def mis_gastos(usuario_id: int = Depends(usuario_actual)):
  return {"usuario": usuario_id, "gastos": ["Café", "Bus"]}

En FastAPI, Depends(usuario_actual) inyecta el resultado de una función ANTES de ejecutar el endpoint: si usuario_actual no encuentra un token válido, lanza un error 401 y el endpoint ni se ejecuta —queda protegido—. El endpoint de login es público (ahí obtienes el token); los demás exigen la dependencia. Este patrón de DEPENDENCIAS (inyección de dependencias, que viste como concepto en React y NestJS) es central en FastAPI: reutilizas lógica (verificar auth, obtener la sesión de BD) declarándola como dependencia. Notas de seguridad ineludibles: la clave secreta y las credenciales van en variables de ENTORNO (nunca en el código); usa HTTPS en producción; y expira los tokens (el exp). La autenticación es donde más cuidado hay que tener —un error aquí compromete todo—.

¿Cómo funciona la autenticación con JWT y por qué las contraseñas nunca se guardan en texto plano?

Mini-reto

Diseña (en tu Python instalado o en papel) la auth de tu API: 1) usa passlib para hashear una contraseña y verificarla (comprueba que una clave correcta da True y una incorrecta False); 2) escribe crear_token y verificar_token con PyJWT, incluyendo expiración; 3) esboza un endpoint /login público y uno /perfil protegido con Depends(usuario_actual). Explica por qué la clave secreta va en una variable de entorno y nunca en el código.

Qué sigue

Ya proteges tu API. La última lección del módulo trae la ESTRUCTURA de un proyecto FastAPI profesional y los TESTS con pytest —cómo organizar el código para que escale y cómo probar tus endpoints automáticamente—. El acabado que separa un experimento de una API lista para producción.