Django-Sitzungen

keenauth.bff.django ergänzt eine Django-4.2-Anwendung oder neuer um Anmeldung. Ihr Server ist der OAuth-Client und behält alle Token serverseitig. Der Browser erhält nur ein verschlüsseltes Session-Cookie mit dem Attribut HttpOnly und sieht niemals ein Access-, Refresh- oder ID-Token. Dies ist das Backend-for-Frontend-(BFF)-Muster. Es ist Teil von keenauth-python, das noch nicht auf PyPI veröffentlicht ist.

Um stattdessen eine API abzusichern, die Bearer-Token empfängt, lesen Sie Ihre API schützen.

Installation

pip install "keenauth-python[django]"

Bevor Sie beginnen

Erstellen Sie im Dashboard in Ihrer Umgebung eine Webanwendung.
Wählen Sie die Client-Authentifizierung: private_key_jwt (empfohlen, PrivateKeyJwt) oder ein Client-Secret (ClientSecretBasic).
Hinterlegen Sie die Redirect-URI https://app.acme.example/auth/callback und die Redirect-URI nach der Abmeldung https://app.acme.example/.
Erzeugen Sie ein Cookie-Secret mit mindestens 32 Zeichen, beispielsweise mit openssl rand -base64 32. Bewahren Sie es in Ihrem Secret-Store auf, nicht im Repository.

Instanz erstellen

import os
from keenauth.bff import BffOptions, ClientSecretBasic, KeenAuthBff

bff = KeenAuthBff(BffOptions(
    issuer="https://acme.eu.keenauth.app",  # your environment's issuer, exactly
    client_id="app_01j9zzzzzzzzzzzzzzzzzzzz",
    client_auth=ClientSecretBasic(os.environ["KEENAUTH_CLIENT_SECRET"]),
    app_base_url="https://app.acme.example",
    secret=os.environ["KEENAUTH_COOKIE_SECRET"],
))

app_base_url ist die öffentliche Adresse Ihrer Anwendung. Das SDK erstellt daraus die Redirect-URI und alle Weiterleitungen, niemals aus dem Header Host oder den Headern X-Forwarded-* der Anfrage. Reines http wird nur für localhost akzeptiert. Die Optionen werden beim Erstellen von KeenAuthBff geprüft, sodass ein Konfigurationsfehler die Anwendung beim Start anhält.

private_key_jwt verwenden

Bei private_key_jwt besitzt die Anwendung kein gemeinsames Geheimnis. Übergeben Sie Ihren privaten Schlüssel an PrivateKeyJwt. Das SDK signiert dann für jede Anfrage an den Token-Endpunkt eine neue Client-Assertion (RFC 7523):

from keenauth.bff import PrivateKeyJwt

client_auth = PrivateKeyJwt(key=os.environ["KEENAUTH_PRIVATE_KEY"])  # unencrypted PEM

Unterstützte Schlüssel: EC P-256 (ES256), EC P-384 (ES384), Ed25519 (EdDSA) und RSA mit mindestens 2048 Bit (standardmäßig PS256; übergeben Sie algorithm="RS256" für RS256).
Jede Assertion hat iss und sub mit Ihrer Client-ID, aud mit dem Issuer, einen zufälligen jti und eine Gültigkeit von 60 Sekunden. Ihre kid ist der RFC-7638-Thumbprint des öffentlichen Schlüssels.
Hinterlegen Sie den öffentlichen Schlüssel an der Anwendung. keenauth.m2m.load_private_key(pem).public_jwk() gibt ihn als JWK zurück.

Um mit Ihrem eigenen Schlüsseldienst (KMS oder HSM) zu signieren, übergeben Sie stattdessen eine Funktion: PrivateKeyJwt(assertion=sign). sign() muss bei jedem Aufruf eine neue signierte Assertion zurückgeben.

Middleware hinzufügen

# settings.py
KEENAUTH_BFF = "myproject.auth.bff"  # dotted path to the KeenAuthBff instance
MIDDLEWARE = [
    # ...
    "keenauth.bff.django.KeenAuthMiddleware",
]

Die Middleware stellt die unten aufgeführten Routen bereit und liest bei jeder anderen Anfrage die Sitzung in request.keenauth.

# views.py
from django.http import HttpResponse
from keenauth.bff.django import require_auth

@require_auth()
def orders(request):
    return HttpResponse(f"Signed in as {request.keenauth.session.user.email}")

Routen

Route	Funktion
`GET /auth/login`	Startet die Anmeldung. Optionale Query-Parameter: `returnTo` (wohin die Person gelangt) und `organization` (Anmeldung in einer Organisation).
`GET /auth/callback`	Schließt die Anmeldung ab und setzt das Session-Cookie.
`GET` oder `POST /auth/logout`	Meldet bei KeenAuth ab und kehrt zu Ihrer Anwendung zurück.

Die Anmeldung verwendet den Authorization-Code-Flow mit PKCE (S256). Die Anfrage wird an den Server übermittelt (PAR), sofern Ihre Umgebung dies unterstützt. Beim Callback prüft das SDK state, iss und das ID-Token einschließlich seines nonce. Jede erfolgreiche Anmeldung erzeugt eine neue Sitzung; die alte wird verworfen.

returnTo muss ein Pfad Ihrer eigenen Anwendung sein, etwa /orders?tab=open. Jeder andere Wert, etwa //evil.example oder eine vollständige URL, wird ignoriert, und die Person gelangt zu /.

Geschützte Views

Versehen Sie eine View mit @require_auth().

Ohne Sitzung:

Eine Seitenanfrage (GET oder HEAD) wird mit returnTo auf /auth/login umgeleitet;
eine Anfrage an /api/… oder mit einer anderen Methode erhält 401 mit einem Problem-Dokument. Übergeben Sie api=True, um auf jedem Pfad mit 401 zu antworten.

Für POST, PUT, PATCH, DELETE und andere unsichere Methoden muss der Browser angeben, dass die Anfrage von Ihrer Anwendung stammt: Sec-Fetch-Site: same-origin oder ein Header Origin, der dem Origin Ihrer Anwendung entspricht. Andere Anfragen erhalten 403. Dies schützt zusätzlich zu SameSite=Lax vor Cross-Site-Request-Forgery.

Sitzung nutzen und Ihre API aufrufen

Der Sitzungskontext enthält:

session: None oder die angemeldete Person. session.user stellt typisierte Claims des ID-Tokens bereit, etwa subject, email, name, org_id und org_roles; alle Claims stehen in session.user.claims. Das Sitzungsobjekt enthält niemals ein Token.
access_token: ein gültiges Access-Token für serverseitige Aufrufe oder None. Senden Sie es nicht an den Browser.

Läuft das Access-Token innerhalb von 60 Sekunden ab, erneuert das SDK es, bevor Ihre View ausgeführt wird. Jede Erneuerung rotiert das Refresh-Token und setzt das neue Session-Cookie in der Antwort. Verweigert der Server das Refresh-Token, endet die Sitzung. Ein vorübergehender Serverfehler lässt die Sitzung unverändert. Gleichzeitige Anfragen in einem Prozess teilen sich eine Erneuerung.

Organisation wechseln

bff.switch_organization_path("org_01j9…", "/dashboard") gibt einen Link zu /auth/login zurück, der die Person erneut in dieser Organisation anmeldet. KeenAuth prüft die Mitgliedschaft. Nach der Anmeldung enthält session.user.org_id die Organisation.

Abmelden

Senden Sie aus einem Formular ein POST an /auth/logout. Das SDK löscht das Session-Cookie (und die gespeicherte Sitzung, falls Sie einen Store verwenden), widerruft das Refresh-Token und leitet den Browser zum Logout-Endpunkt Ihrer Umgebung weiter, der ihn zu Ihrer Anwendung zurückführt. Eine Anfrage, die der Browser als von einer anderen Website stammend kennzeichnet, wird abgelehnt. Browser, die kein Sec-Fetch-Site senden, können sich nur über ein POST von Ihren eigenen Seiten abmelden.

Session-Speicherung

Standardmäßig liegt die gesamte Sitzung im Cookie, verschlüsselt und mit AES-256-GCM authentifiziert, mit einem aus secret abgeleiteten Schlüssel. Ein geändertes oder kopiertes Cookie wird abgelehnt. Das Cookie heißt __Host-keenauth_session.0 und wird mit Secure, HttpOnly, SameSite=Lax und Path=/ gesetzt. Auf http://localhost entfallen das Präfix __Host- und Secure. Große Sitzungen werden auf bis zu drei Cookies aufgeteilt.

Wenn die Token auf dem Server bleiben sollen, übergeben Sie store= mit einem Objekt, das get(id), set(id, session, ttl_seconds) und delete(id) bereitstellt, etwa mit Redis als Backend. Das Cookie enthält dann nur eine verschlüsselte zufällige Sitzungs-ID. Jede Anmeldung erzeugt eine neue ID und löscht den vorherigen Datensatz. Der Store enthält Token, beschränken Sie daher den Zugriff darauf. MemorySessionStore ist nur für Entwicklung und Tests gedacht.

Eine Sitzung dauert höchstens 7 Tage (session_max_age); eine Erneuerung verlängert sie nicht. Um das Secret zu ändern, übergeben Sie eine Liste: secret=[new_secret, old_secret]. Entfernen Sie das alte nach session_max_age.

Aktuelle Einschränkungen

DPoP-gebundene Token und Back-Channel-Logout werden noch nicht unterstützt.
Erneuerungen werden nur innerhalb eines Serverprozesses geteilt. Bei mehreren Prozessen lässt die Anwendungseinstellung refresh_reuse_interval_s (Standard 5 Sekunden) eine parallele Erneuerung erfolgreich sein; setzen Sie sie auf 0, beendet die zweite Erneuerung die Sitzung.