Benutzersystem — Registrierung, Anmeldung, JWT-Authentifizierung

In diesem Kapitel lernst du das JWT-Authentifizierungsschema von FastAPI kennen und verstehst die Unterschiede zur Session-Authentifizierung von Django/Flask.


JWT vs Session-Authentifizierung

Django und Flask verwendenSession-AuthentifizierungDer Server speichert den Benutzerstatus, und nur die Session-ID wird im Cookie gespeichert.

FastAPI empfiehltJWT-Authentifizierung: Nachdem sich der Benutzer angemeldet hat, erhält er ein Token. Nachfolgende Anfragen können das Token zur Authentifizierung mitführen.

FunktionenSession(Django/Flask)JWT(FastAPI)
SpeicherortServerseitig (Speicher/Datenbank)Clientseitig (Cookie/LocalStorage)
ErweiterbarkeitDer Server muss die Session teilenZustandslos, unterstützt natürlich verteilte Systeme
Anwendbare SzenarienServerseitig gerenderte WebsitesAPI + SPA / Mobile
AblaufkontrolleDer Server kann es jederzeit ungültig machenWährend der gesamten Gültigkeitsdauer des Tokens gültig

Abhängigkeiten installieren

(venv) $ pip install passlib python-jose python-multipart
  • passlib: Passwort-Hashing (analog zu werkzeug.security)
  • python-jose: JWT-Generierung und -Verifizierung
  • python-multipart: Formularübermittlung verarbeiten (OAuth2-Login-Formular)

Das User-Modell definieren

Beispiel

# Dateipfad: models.py, neue Ergänzungen
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True, index=True)
    username = Column(String(50), unique=True, nullable=False)
    email = Column(String(120), unique=True, nullable=False)
    hashed_password = Column(String(256), nullable=False)

    def set_password(self, password: str):
        """Passwort hashen"""
        self.hashed_password = pwd_context.hash(password)

    def verify_password(self, password: str) -> bool:
        """Passwort überprüfen"""
        return pwd_context.verify(password, self.hashed_password)

Migrationen generieren und ausführen:

(venv) $ alembic revision --autogenerate -m "新增 User 模型"
(venv) $ alembic upgrade head

JWT-Hilfsfunktionen

Beispiel

# Dateipfad: auth.py (neue Datei)
from datetime import datetime, timedelta
from jose import JWTError, jwt
from passlib.context import CryptContext
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer

# Geheimer Schlüssel (in Produktion aus Umgebungsvariablen auslesen)
SECRET_KEY = "your-secret-key-change-in-production"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 60 * 24  # Token-Gültigkeitsdauer: 24 Stunden

# OAuth2PasswordBearer teilt FastAPI mit: fromRequest headers Authorization: Bearer <token> Mediummention JWT abrufen
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

def create_access_token(data: dict) -> str:
    """JWT-Token generieren"""
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

def decode_access_token(token: str) -> dict | Keine:
    """JWT-Token verifizieren und decodieren"""
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        return payload
    except JWTError:
        return None

Routenregistrierung

Beispiel

# Dateipfad: routers/users.py
from fastapi import APIRouter, Depends, HTTPException, Request, Form
from fastapi.templating import Jinja2Templates
from sqlalchemy.orm import Session
from database import get_db
from models import User
from schemas import UserCreate, UserResponse
from auth import create_access_token

router = APIRouter(prefix="/users", tags=["User"])
templates = Jinja2Templates(directory="templates")

@router.post("/register", response_model=UserResponse)
def register(
    username: str = Form(...),
    email: str = Form(...),
    password: str = Form(...),
    db: Session = Depends(get_db)
):
    """Benutzerregistrierung"""
    # Prüfen, ob Benutzername und E-Mail bereits existieren
    if db.query(User).filter(User.username == username).first():
        raise HTTPException(status_code=400, detail="Benutzername wird bereits verwendet")
    if db.query(User).filter(User.email == email).first():
        raise HTTPException(status_code=400, detail=E-Mail ist bereits registriert)

    user = User(username=username, email=email)
    user.set_password(password)
    db.add(user)
    db.commit()
    db.refresh(user)
    return user

Login-Route (JWT ausstellen)

Beispiel

# An Datei anhängen: routers/users.py
from fastapi.security import OAuth2PasswordRequestForm
from auth import create_access_token

@router.post("/token")
def login_for_access_token(
    form_data: OAuth2PasswordRequestForm = Depends(),
    db: Session = Depends(get_db)
):
    """
Anmelden und Token abrufen
OAuth2PasswordRequestForm verwenden: Feldnamen sind username und password (Formularformat).
    """

    user = db.query(User).filter(User.username == form_data.username).first()
    if not user or not user.verify_password(form_data.password):
        raise HTTPException(
            status_code=401,
            detail="Ungültiger Benutzername oder Passwort",
            headers={"WWW-Authenticate": "Bearer"}
        )

    # JWT ausstellen: enthält nur user_id (darf keine sensiblen Informationen enthalten)
    access_token = create_access_token(data={"sub": str(user.id)})
    return {"access_token": access_token, "token_type": "bearer"}

Im JWT-TokensubEs ist das Standard-Subjektfeld, das die Benutzerkennung speichert. Das Token selbst ist nicht verschlüsselt (nur Base64-kodiert), daher sollten Sieauf keinen Fallkeine sensiblen Informationen wie Passwörter hineingeben. Wenn Sie Verschlüsselung wünschen, verwenden Sie JWE statt JWT.


JWT-Schutz in Routen verwenden

Beispiel

# Abhängigkeitsfunktion zum Abrufen des aktuellen Benutzers
from auth import oauth2_scheme, decode_access_token

def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: Session = Depends(get_db)
):
    """Den aktuellen Benutzer aus dem JWT-Token parsen"""
    payload = decode_access_token(token)
    if payload is None:
        raise HTTPException(status_code=401, detail="Token ungültig oder abgelaufen")

    user_id = payload.get("sub")
    user = db.query(User).filter(User.id == int(user_id)).first()
    if user is None:
        raise HTTPException(status_code=401, detail=“Benutzer existiert nicht”)

    return user

# In Routen injizieren, die eine Anmeldung erfordern
@router.get("/me", response_model=UserResponse)
def read_current_user(current_user: User = Depends(get_current_user)):
    """Aktuelle Benutzerinformationen abrufen (Anmeldung erforderlich)"""
    return current_user

Für SSR-Seiten wird JWT normalerweise in einem Cookie gespeichert (anstelle des Authorization-Headers), und in Template-Routen wird das Token zur Verifizierung aus dem Cookie extrahiert.


Kapitelzusammenfassung

In diesem Kapitel haben Sie die JWT-Authentifizierung von FastAPI implementiert: passlib für Passwort-Hashing, python-jose zum Ausstellen und Verifizieren von JWTs, OAuth2PasswordBearer zum Extrahieren von Tokens und Depends für die Authentifizierungs-Dependency-Injection.

Im Gegensatz zur Session-Authentifizierung von Django/Flask ist JWT eine zustandslose Lösung, die besser für Szenarien mit Frontend-/Backend-Trennung geeignet ist.

Weitere Erweiterungen