Eine Django-API schützen

Diese Schnellstartanleitung schützt eine Django-API mit KeenAuth-Zugriffstokens. Sie fügen den @protect-View-Dekorator des Python-SDK hinzu, verlangen einen Scope für eine View und testen die API offline mit dem Test-Kit des SDK. Das Beispiel verwendet Django 5.2 und keine Datenbank.

Die API hat drei Endpunkte:

Bevor Sie beginnen

• Eine KeenAuth-Umgebung. Ihr Issuer sieht etwa so aus: https://your-environment.eu.keenauth.app.
• Eine in der Umgebung registrierte API (API anlegen). Ihr identifier, zum Beispiel https://api.example.com, ist die Audience der Tokens, die Ihre API akzeptiert.
• Der messages:read-Scope für diese API, gewährt der Anwendung, die sie aufruft.
• Python 3.10 oder neuer.

1. SDK installieren

pip install "keenauth-python[django]"

Das SDK ist noch nicht veröffentlicht. Bis dahin installiert das Beispiel es aus dem SDK-Quellcode. Das Beispiel fixiert jedes Paket auf eine exakte Version in requirements.txt.

2. Konfigurieren

project/settings.py liest jeden Wert aus Umgebungsvariablen:

3. Ihre Views schützen

@protect(protector) verlangt ein gültiges Token und legt die geprüften Claims in request.auth ab; scopes=[...] verlangt zusätzlich Scopes. Schlägt eine Prüfung fehl, gibt sie eine application/problem+json-Antwort zurück, bevor die View ausgeführt wird.

@require_GET
def public(request: HttpRequest) -> JsonResponse:
    # No token needed.
    return JsonResponse({"message": "Hello from a public endpoint."})


@require_GET
@protect(protector)
def private(request: HttpRequest) -> JsonResponse:
    # Any valid access token for this API; the verified claims are in request.auth.
    return JsonResponse({"message": "Hello from a private endpoint.", "sub": request.auth.subject})


@require_GET
@protect(protector, scopes=["messages:read"])
def messages(request: HttpRequest) -> JsonResponse:
    # A valid access token that also carries the messages:read scope.
    return JsonResponse({"messages": ["Hello from a scoped endpoint."]})

api/auth.py baut den Protector beim Start aus den Einstellungen auf (ApiConfig.ready in api/apps.py), sodass eine fehlende Einstellung den Server vor der ersten Anfrage stoppt. Der Verifier lädt die Signaturschlüssel beim ersten Token aus Ihrer Umgebung.

@cache
def get_protector() -> Protector:
    if not settings.KEENAUTH_ISSUER or not settings.KEENAUTH_AUDIENCE or not settings.KEENAUTH_PUBLIC_BASE_URL:
        raise ImproperlyConfigured("KEENAUTH_ISSUER, KEENAUTH_AUDIENCE and PUBLIC_BASE_URL are required")
    # The verifier refuses an issuer under the reserved .invalid domain, so a test token can never pass here.
    verifier = Verifier(VerifierConfig(issuer=settings.KEENAUTH_ISSUER, audience=settings.KEENAUTH_AUDIENCE))
    return Protector(
        verifier,
        public_base_url=settings.KEENAUTH_PUBLIC_BASE_URL,
        revocation=revocation,
        # The error never contains the token or claim values; never log the Authorization or DPoP header.
        on_error=lambda err: log.warning("rejected: %s", err),
    )


@cache
def get_webhook() -> Optional[RevocationWebhook]:
    """The token.revoked webhook, or None when KEENAUTH_WEBHOOK_SECRET is not set. A malformed secret raises
    WebhookSecretError (without echoing it), so ApiConfig.ready stops the server at startup."""
    if not settings.KEENAUTH_WEBHOOK_SECRETS:
        return None
    return RevocationWebhook(settings.KEENAUTH_WEBHOOK_SECRETS, revocation)


class ProtectorProxy:
    """Hands each request to `get_protector()`, so the `@protect` decorators can be applied at import time."""

    def authenticate(self, req: RequestInfo, requirement: Optional[Requirement] = None) -> AccessClaims:
        return get_protector().authenticate(req, requirement)


protector = ProtectorProxy()

4. Starten und die API aufrufen

export DJANGO_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(50))')"
export KEENAUTH_ISSUER=https://your-environment.eu.keenauth.app
export KEENAUTH_AUDIENCE=https://api.example.com
export PUBLIC_BASE_URL=https://api.example.com
python manage.py runserver 8080

runserver ist nur für die Entwicklung gedacht; in Produktion betreiben Sie project.wsgi unter einem WSGI-Server.

Für einen ersten Aufruf holen Sie ein Token über den Client-Credentials-Grant einer Machine-to-Machine-Anwendung, die den messages:read-Scope für Ihre API besitzt:

ACCESS_TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://api.example.com \
  -d scope=messages:read \
  https://your-environment.eu.keenauth.app/oauth2/token | jq -r .access_token)

curl -i http://localhost:8080/api/messages -H "Authorization: Bearer $ACCESS_TOKEN"

5. Ohne Netzwerk testen

keenauth.testing erstellt Tokens, die mit einem öffentlichen Testschlüssel signiert sind, und testing.verifier akzeptiert nur diese Tokens. Die Tests ersetzen get_protector durch einen Protector, der diesen Verifier verwendet; sie benötigen daher kein Netzwerk, kein KeenAuth-Konto und keinen Testschalter in den Einstellungen. Siehe Offline-Test-Kit.

class ProtectedAPITest(SimpleTestCase):
    def setUp(self) -> None:
        self.cache = MemoryRevocationCache()
        test_protector = Protector(testing.verifier(audience=AUDIENCE), public_base_url=BASE_URL, revocation=self.cache)
        patcher = mock.patch.object(auth, "get_protector", return_value=test_protector)
        patcher.start()
        self.addCleanup(patcher.stop)

    def test_scope(self) -> None:
        self.assert_problem(self.get("/api/messages", testing.mint_access_token(AUDIENCE)), 403, "insufficient_scope",
                            'scope="messages:read"')
        tok = testing.mint_access_token(AUDIENCE, claims={"scope": "profile messages:read"})
        self.assertEqual(self.get("/api/messages", tok).status_code, 200)

set -a; . ./.env.example; set +a
DJANGO_SECRET_KEY=insecure-test-only python manage.py test

Die Tests des Beispiels prüfen, dass ein gültiges Token akzeptiert wird und dass ein fehlendes, abgelaufenes oder für eine andere Audience ausgestelltes Token, ein fehlender Scope, ein Token in der URL-Query und ein widerrufenes Token mit den unten genannten Statuscodes abgelehnt werden. Außerdem senden sie ein DPoP-gebundenes Token mit einem Nachweis für PUBLIC_BASE_URL und prüfen, dass der Produktions-Protector den Test-Issuer ablehnt. Die Tests senden zudem signierte token.revoked-Zustellungen: Eine gültige widerruft das Token, eine gefälschte, manipulierte oder veraltete erhält 400 und widerruft nichts, und eine wiederholte hat genau eine Wirkung.

Antworten

Der Body ist application/problem+json, und der WWW-Authenticate-Header enthält die Standard-Challenge; Django fasst mehrere Challenges in einem Header zusammen. Die vollständige Tabelle steht unter API mit Middleware schützen.

Hinter einem Proxy

Wenn Clients DPoP verwenden, prüft die Middleware, dass jeder Nachweis für die URL erstellt wurde, die der Client aufgerufen hat. Setzen Sie PUBLIC_BASE_URL auf die externe URL, die Clients aufrufen, zum Beispiel https://api.example.com, auch hinter einem Proxy oder Load Balancer. Die Einstellung ist erforderlich und muss https verwenden (http nur für localhost, 127.0.0.1 oder [::1]); ohne sie startet die App nicht. Die Middleware liest selbst niemals X-Forwarded-*-Header; Django wertet sie nur aus, wenn Sie SECURE_PROXY_SSL_HEADER oder USE_X_FORWARDED_HOST setzen, und wenn PUBLIC_BASE_URL gesetzt ist, hängt die geprüfte URL nicht von ihnen ab.

Widerrufene Tokens

Ein Zugriffstoken bleibt bis zu seinem Ablauf gültig. Deshalb teilt KeenAuth Ihrer API mit, wenn Tokens widerrufen werden. Das Beispiel übergibt dem Protector einen In-Memory-Widerrufs-Cache und stellt unter POST /webhooks/keenauth (api/webhook.py) einen token.revoked-Webhook bereit, der diesen Cache speist.

1. Legen Sie im Dashboard einen Webhook-Endpunkt mit der URL https://<your host>/webhooks/keenauth an, der token.revoked abonniert, und exportieren Sie sein Signaturgeheimnis als KEENAUTH_WEBHOOK_SECRET.
2. Der Handler prüft die Signatur mit dem SDK auf dem Rohbody und antwortet mit 400, wenn sie ungültig ist oder der Zeitstempel mehr als fünf Minuten abweicht. Er ordnet den Selektor des Ereignisses (access_token, session, user, client, org, org_user, client_user) einer Widerrufsmarkierung zu und antwortet mit 204; die Middleware lehnt danach jedes passende Token ab, das vor not_before ausgestellt wurde.
3. KeenAuth liefert mindestens einmal, daher wendet der Handler jedes webhook-id genau einmal an. Kann die Markierung nicht gespeichert werden, antwortet er mit 503, und KeenAuth liefert das Ereignis erneut. Andere Ereignistypen und Selektoren, auf die kein Zugriffstoken passen kann (refresh_family, api), ignoriert er.

Der Handler protokolliert die Ereignis-ID, den Selektortyp und den Grund, niemals den Body, eine Signatur oder das Geheimnis. Jeder Worker-Prozess hat seinen eigenen Cache; bei mehreren Workern oder Instanzen verwenden Sie stattdessen einen gemeinsamen Speicher. Siehe Widerrufs-Cache.

Nächste Schritte

• API mit Middleware schützen: Flask, Step-up-Anforderungen, DPoP und alle Optionen.
• Tokens prüfen: der Verifier unter der Middleware.
• Offline-Test-Kit.