¿Cómo implementas autenticación (OAuth2/JWT)?

Question

Accepted Answer

FastAPI proporciona herramientas integradas (`OAuth2PasswordBearer`, utilidades de seguridad) para implementar autenticación, comúnmente usando **flujo de contraseña OAuth2 con tokens JWT**. El patrón combina la emisión de tokens (login) con una dependencia que valida el token en rutas protegidas.

## Hashing de contraseñas e issuance de JWT en login

```python
from passlib.context import CryptContext
from jose import jwt
from datetime import datetime, timedelta

pwd = CryptContext(schemes=["bcrypt"])    # secure password hashing

@app.post("/login")
def login(form: OAuth2PasswordRequestForm = Depends()):
    user = get_user(form.username)
    if not user or not pwd.verify(form.password, user.hashed_password):  # constant-time check
        raise HTTPException(401, "Invalid credentials")
    # issue a signed JWT containing the user identity + expiry
    token = jwt.encode(
        {"sub": user.username, "exp": datetime.utcnow() + timedelta(minutes=30)},
        SECRET_KEY, algorithm="HS256",
    )
    return {"access_token": token, "token_type": "bearer"}
```

Las contraseñas se **hashean** (bcrypt) — nunca se almacenan en texto plano. En un login válido, se emite un **JWT**: un token firmado que porta la identidad del usuario y una fecha de expiración.

## Validación del token en rutas protegidas (una dependencia)

```python
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="login")   # extracts the Bearer token

def get_current_user(token: str = Depends(oauth2_scheme)):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])   # verify signature + expiry
        username = payload.get("sub")
    except JWTError:
        raise HTTPException(401, "Invalid token")
    user = get_user(username)
    if not user:
        raise HTTPException(401, "User not found")
    return user

@app.get("/me")
def read_me(user: User = Depends(get_current_user)):     # PROTECTED — requires a valid token
    return user
```

Una dependencia `get_current_user` extrae y **verifica** el JWT (firma + expiración), carga el usuario, e se inyecta en endpoints protegidos — cualquier ruta que dependa de ella requiere autenticación.

## Autorización (roles/scopes)

```python
def require_admin(user: User = Depends(get_current_user)):
    if not user.is_admin:
        raise HTTPException(403, "Forbidden")     # authorization check
    return user
# OAuth2 SCOPES provide fine-grained permission control
```

## Por qué es importante

La autenticación es esencial y **crítica para la seguridad** — casi toda API real necesita proteger rutas, y cometer errores en autenticación crea vulnerabilidades serias.

Comprender el enfoque de FastAPI es importante: proporciona los bloques de construcción (`OAuth2PasswordBearer`, utilidades de seguridad) para el patrón estándar **OAuth2-password-flow-with-JWT**, que aprovecha elegantemente las fortalezas de FastAPI — un endpoint de login emite un token firmado, y una dependencia **`get_current_user`** lo valida, protegiendo limpiamente cualquier ruta que dependa de él (el patrón idiomático de autenticación en FastAPI).

Varios aspectos son críticos de implementar correctamente: **hashear contraseñas** (bcrypt, nunca texto plano, con verificación en tiempo constante), **firmar y verificar JWTs** correctamente (validación de firma + expiración), distinguir **autenticación** (quién eres) de **autorización** (qué puedes hacer, mediante verificaciones de rol/scope), y mantener la clave secreta segura.

Saber cómo implementar este patrón de forma segura — issuance de tokens, la dependencia de validación, y autorización — es conocimiento fundamental de nivel senior para construir aplicaciones FastAPI seguras, ya que la autenticación es tanto ubicua como una fuente frecuente de errores peligrosos cuando se implementa incorrectamente.