Rustango docs
← Authentifizierung

Auth-Backends

Ein Auth-Backend beantwortet eine einzige Frage: wer ist der Benutzer bei einer eingehenden Anfrage? Rustango lässt Sie mehrere davon stapeln — HTTP Basic, API-Schlüssel, JWT — zu einer Kette, die die Auth-Middleware der Reihe nach durchprobiert, sodass eine Anwendung Menschen und Maschinen auf denselben Routen akzeptieren kann. Die Kette ist eine reine Konfigurationsliste, an axum verdrahtet. Kombinieren Sie es mit require_auth / require_perm, um Routen abzusichern, und dem CurrentUser-Extraktor, um das Ergebnis zu lesen.

Auth-Backends in Rustango: eine Anfrage durchläuft eine Kette von Backends (ModelBackend, ApiKeyBackend, JwtBackend); das erste, das den Anmeldenachweis erkennt, gewinnt und injiziert CurrentUser, dann prüft require_perm einen Codename

Ein Begriff hier neu? Backend, Middleware, Extraktor, Berechtigungs-Codename — siehe das Glossar.

Quelle: rustango::tenancy::auth_backends (AuthBackend, ModelBackend, ApiKeyBackend, JwtBackend, AuthUser, AuthError) und rustango::tenancy::{RouterAuthExt, CurrentUser} — hinter dem Feature tenancy.

Ausführbare Version: jeder Ausschnitt ist aus auth_backends_doc.rs kopiert (cargo test -p rustango --features sqlite,tenancy --test auth_backends_doc).

Inhaltsverzeichnis


Die Kette

Sie übergeben require_auth einen Vec<Arc<dyn AuthBackend>>. Bei jeder Anfrage probiert die Middleware sie der Reihe nach durch:

  • das erste Backend, das den Anmeldenachweis erkennt, gewinnt (gibt den Benutzer zurück);
  • ein Backend, das ihn nicht erkennt, gibt „keiner" zurück, und das nächste wird probiert;
  • wenn ein Backend hart fehlschlägt, stoppt die Kette mit diesem Fehler: ein inaktives Konto mit gültigem Credential ist 403, eine Sperre 429 (oder 503, wenn das Passwort-Hashing ausgelastet ist), ein ungültiges Token 401;
  • wenn keines passt, erhält die Anfrage 401 (mit require_auth) oder fährt anonym fort (mit optional_auth).
use std::sync::Arc;
use rustango::tenancy::auth_backends::{ApiKeyBackend, AuthBackend, ModelBackend};

let backends: Vec<Arc<dyn AuthBackend>> = vec![
    Arc::new(ModelBackend),    // HTTP Basic  → humans
    Arc::new(ApiKeyBackend),   // Bearer key  → machines
];

Die eingebauten Backends

BackendAnmeldenachweis, den es liestIdentifiziert einen Benutzer über
ModelBackendAuthorization: Basic <base64(user:pass)>Benutzername + argon2id-Passwortprüfung gegen rustango_users
ApiKeyBackendAuthorization: Bearer <prefix.secret>die Tabelle rustango_api_keys (siehe API-Schlüssel)
JwtBackendAuthorization: Bearer <jwt>ein signiertes HS256-Token (siehe JWT)

ApiKeyBackend und JwtBackend lesen beide Bearer und unterscheiden anhand der Form (das erste Punkt-Segment eines API-Schlüssels ist genau 8 Zeichen lang). Ein Bearer-Wert in JWT-Form, der die Prüfung nicht besteht, ist ein hartes 401 und geht nicht an das nächste Backend. ModelBackend zählt falsche Passwörter pro Mandant, IP und Benutzername; wiederholtes Raten bekommt 429. Konstruieren Sie JwtBackend mit einem Geheimnis von mindestens 32 Byte (JwtBackend::new(secret) panikt andernfalls):

use rustango::tenancy::auth_backends::JwtBackend;

let backends: Vec<Arc<dyn AuthBackend>> = vec![
    Arc::new(ModelBackend),
    Arc::new(JwtBackend::new(jwt_secret_at_least_32_bytes.to_vec())),
];

Auf einer Tenant-Route müssen die Claims tenant und org_id des Tokens zum aufgelösten Tenant passen, und MCP-Agent-Token (kind-Claim) werden abgewiesen. Prägen Sie mit dem JwtAuth-Login oder JwtBackend::issue_for_tenant; issue-Token gelten nur ohne aufgelösten Tenant. Direkt nach einem Logout-all prägen Sie mit issue_for_user / issue_for_tenant_user: ein issue-Token aus dieser Sekunde wird abgewiesen.

JwtBackend akzeptiert die Access-Token, die JwtLifecycle ausstellt, und weist dessen Refresh-Token zurück — beide sind bis auf typ auf der Leitung identisch, ein als Bearer vorgelegter Refresh-Token wäre also ein Zugangsnachweis mit Tagen statt Minuten Lebensdauer.

Widerruf ist optional und standardmäßig aus. Ein einfaches JwtBackend konsultiert nie eine Sperrliste, ein von /api/auth/logout widerrufener Token authentifiziert sich über dieses Backend also weiter, bis er von selbst abläuft. Teilen Sie einen Speicher zwischen Lifecycle und Backend, damit Logout wirksam wird:

use rustango::jti_store::{InMemoryJtiStore, JtiStore};

let shared: Arc<dyn JtiStore> = Arc::new(InMemoryJtiStore::new()); // in Produktion Redis
let lifecycle = JwtLifecycle::new(secret.clone()).with_jti_store(Arc::clone(&shared));
let backend = JwtBackend::new(secret).with_jti_store(Arc::clone(&shared));

Es muss derselbe Speicher sein. Zwei Instanzen zu verdrahten sieht konfiguriert aus und erzwingt nichts: Logout schreibt in den einen, die Verifikation liest den anderen. Siehe Widerruf und der JTI-Speicher.

Schreiben Sie ein eigenes Backend, indem Sie den Trait implementieren (eine einzige async-Methode, die die Parts der Anfrage inspiziert und Option<AuthUser> zurückgibt):

use async_trait::async_trait;   // add `async-trait` to your Cargo.toml
use axum::http::request::Parts;
use rustango::sql::Pool;
use rustango::tenancy::auth_backends::{AuthBackend, AuthError, AuthUser};

struct HeaderBackend;

#[async_trait]
impl AuthBackend for HeaderBackend {
    async fn authenticate(&self, parts: &Parts, _pool: &Pool)
        -> Result<Option<AuthUser>, AuthError>
    {
        // ...inspect parts.headers, return Some(AuthUser{..}) or Ok(None)
        Ok(None)
    }
}

Routen absichern: require_auth

RouterAuthExt fügt die Middleware hinzu. require_auth weist anonyme Anfragen mit 401 ab; optional_auth lässt sie durch (sodass ein Handler auf angemeldet vs. nicht verzweigen kann):

use rustango::tenancy::RouterAuthExt;

let app = Router::new()
    .route("/profile", get(profile))
    .require_auth(backends);           // 401 if no backend matches

Vor 0.57.11 nahmen diese einen Pool. Das tun sie nicht mehr, und die Änderung ist ein Sicherheitsfix, kein Aufräumen. Der Pool wurde beim Bauen des Routers erfasst und für jede Anfrage wiederverwendet, sodass eine von einem Tenant ausgestellte Anmeldeinformation auf dem Host eines anderen Tenants authentifizierte — die Backends suchten den Benutzer in der Datenbank, mit der der Router zufällig gebaut worden war, und is_superuser reiste ohne erneute Abfrage in einer Request-Extension weiter.

Der Pool kommt jetzt aus dem Tenant, der für jede Anfrage aufgelöst wird. Die Migration besteht im Weglassen des Arguments:

.require_auth(backends, pool.clone())  →  .require_auth(backends)
.require_perm("post.add", pool)        →  .require_perm("post.add")

Hängen Sie den Tenancy-Layer außerhalb davon ein. Ohne Tenant-Kontext in den Request-Extensions schlagen sie geschlossen mit 500 fehl, statt eine Datenbank zu raten.

Verifiziertes Verhalten:

// no credentials               → 401
// Basic alice:<correct>        → 200
// Basic alice:<wrong>          → 401   (no backend accepted; no enumeration)
// Bearer <valid api key>       → 200

Den Benutzer lesen: CurrentUser

Handler lesen den authentifizierten Benutzer mit dem CurrentUser-Extraktor. Er ist unfehlbar — Some(user), wenn ein Backend einen aufgelöst hat, sonst None:

use rustango::tenancy::CurrentUser;

async fn profile(CurrentUser(user): CurrentUser) -> Response {
    match user {
        Some(u) => format!("hello {}", u.username).into_response(),
        None    => StatusCode::UNAUTHORIZED.into_response(),
    }
}

Fallstrick: weil CurrentUser unfehlbar ist, führt das Vergessen von require_auth nicht zu einem Kompilierfehler — jede Anfrage sieht einfach None. Hinter require_auth erhalten anonyme Anfragen bereits 401, sodass user dort stets Some ist.


Berechtigungen: require_perm

require_perm sichert eine Route über einen Berechtigungs-Codename ab ({table}.{action}, z. B. post.add). Wenden Sie es auf den inneren Sub-Router an und require_auth auf den äußeren, sodass der Benutzer aufgelöst wird, bevor die Berechtigung geprüft wird:

let admin = Router::new()
    .route("/admin", get(admin_only))
    .require_perm("post.add");     // inner: needs the codename

let app = Router::new()
    .route("/profile", get(profile))
    .merge(admin)
    .require_auth(backends);       // outer: resolves the user first
// alice (granted post.add)   → /admin 200
// bob   (authed, no grant)   → /admin 403
// anonymous                  → /admin 401   (auth runs first)

Auflösung: ein (aktiver) Superuser passiert alles; ein deaktivierter Benutzer wird selbst mit Erteilungen abgelehnt; eine explizite Überschreibung pro Benutzer gewinnt über Rollen-Erteilungen; andernfalls passiert jede Rolle, die der Benutzer hält und die den Codename erteilt. Erteilen Sie mit set_user_perm_pool / Rollen über create_role_pool + assign_role_pool (die Berechtigungstabellen werden von ensure_tables_pool erstellt).

ViewSet und die Template-Views lesen für ihre Codenamen-Prüfung denselben Benutzer, aber nur an tenant_router. An einem .router(..) mit festem Pool lehnen sie einen von diesen Backends aufgelösten Benutzer ab (403): Dieser Pool enthält keine Benutzer eines Tenants.


Siehe auch

  • API-Schlüssel und JWT — die Anmeldenachweise, die ApiKeyBackend / JwtBackend konsumieren.
  • Passwörter — das Hashing, gegen das ModelBackend verifiziert.
  • Zugriffs-Dekoratoren — Absicherung pro Handler mit login_required / permission_required, die dekorator-artige Alternative zu require_auth/require_perm.
  • Sessions — cookie-basierte Authentifizierung für Browser.