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.
Ein Begriff hier neu? Backend, Middleware, Extraktor, Berechtigungs-Codename — siehe das Glossar.
Quelle:
rustango::tenancy::auth_backends(AuthBackend,ModelBackend,ApiKeyBackend,JwtBackend,AuthUser,AuthError) undrustango::tenancy::{RouterAuthExt, CurrentUser}— hinter dem Featuretenancy.Ausführbare Version: jeder Ausschnitt ist aus
auth_backends_doc.rskopiert (cargo test -p rustango --features sqlite,tenancy --test auth_backends_doc).
Inhaltsverzeichnis
- Die Kette · Die eingebauten Backends
- Routen absichern: require_auth
- Den Benutzer lesen: CurrentUser
- Berechtigungen: require_perm
- Siehe auch
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 Sperre429(oder503, wenn das Passwort-Hashing ausgelastet ist), ein ungültiges Token401; - wenn keines passt, erhält die Anfrage
401(mitrequire_auth) oder fährt anonym fort (mitoptional_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
| Backend | Anmeldenachweis, den es liest | Identifiziert einen Benutzer über |
|---|---|---|
ModelBackend | Authorization: Basic <base64(user:pass)> | Benutzername + argon2id-Passwortprüfung gegen rustango_users |
ApiKeyBackend | Authorization: Bearer <prefix.secret> | die Tabelle rustango_api_keys (siehe API-Schlüssel) |
JwtBackend | Authorization: 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, undis_superuserreiste 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
500fehl, 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
CurrentUserunfehlbar ist, führt das Vergessen vonrequire_authnicht zu einem Kompilierfehler — jede Anfrage sieht einfachNone. Hinterrequire_autherhalten anonyme Anfragen bereits401, sodassuserdort stetsSomeist.
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/JwtBackendkonsumieren. - Passwörter — das Hashing, gegen das
ModelBackendverifiziert. - Zugriffs-Dekoratoren — Absicherung pro Handler mit
login_required/permission_required, die dekorator-artige Alternative zurequire_auth/require_perm. - Sessions — cookie-basierte Authentifizierung für Browser.
