Backends d'authentification
Un backend d'authentification répond à une seule question : étant donné une
requête entrante, qui est l'utilisateur ? Rustango vous permet d'en empiler
plusieurs — HTTP Basic, clé d'API, JWT — dans une chaîne que le middleware
d'authentification essaie dans l'ordre, de sorte qu'une même application peut
accepter humains et machines sur les mêmes routes. La chaîne n'est qu'une
liste de configuration, câblée à axum. Associez-la à
require_auth / require_perm pour verrouiller les routes et à l'extracteur
CurrentUser pour lire le résultat.
Un terme vous est inconnu ici ? Backend, middleware, extracteur, codename de permission — voir le glossaire.
Source :
rustango::tenancy::auth_backends(AuthBackend,ModelBackend,ApiKeyBackend,JwtBackend,AuthUser,AuthError) etrustango::tenancy::{RouterAuthExt, CurrentUser}— derrière la fonctionnalitétenancy.Version exécutable : chaque extrait est copié depuis
auth_backends_doc.rs(cargo test -p rustango --features sqlite,tenancy --test auth_backends_doc).
Table des matières
- La chaîne · Les backends intégrés
- Verrouiller les routes : require_auth
- Lire l'utilisateur : CurrentUser
- Permissions : require_perm
- Voir aussi
La chaîne
Vous passez à require_auth un Vec<Arc<dyn AuthBackend>>. À chaque requête, le
middleware les essaie dans l'ordre :
- le premier backend qui reconnaît l'identifiant l'emporte (renvoie l'utilisateur) ;
- un backend qui ne le reconnaît pas renvoie « aucun » et le suivant est essayé ;
- si un backend échoue durement, la chaîne s'arrête avec cette erreur : un
compte inactif avec un identifiant valide donne
403, un verrouillage429(ou503si le hachage des mots de passe est saturé), un jeton invalide401; - si aucun ne correspond, la requête reçoit un
401(avecrequire_auth) ou poursuit de manière anonyme (avecoptional_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
];
Les backends intégrés
| Backend | Identifiant qu'il lit | Identifie un utilisateur par |
|---|---|---|
ModelBackend | Authorization: Basic <base64(user:pass)> | nom d'utilisateur + vérification du mot de passe argon2id contre rustango_users |
ApiKeyBackend | Authorization: Bearer <prefix.secret> | la table rustango_api_keys (voir Clés d'API) |
JwtBackend | Authorization: Bearer <jwt> | un jeton HS256 signé (voir JWT) |
ApiKeyBackend et JwtBackend lisent tous deux Bearer et lèvent l'ambiguïté
par la forme (le premier segment séparé par un point d'une clé d'API fait
exactement 8 caractères). Une valeur Bearer qui a la forme d'un JWT mais
échoue à la vérification est un 401 ferme, pas un passage au backend suivant.
ModelBackend compte les mots de passe faux par tenant, IP et nom d'utilisateur ;
des essais répétés reçoivent 429. Construisez JwtBackend avec un secret d'au moins 32
octets (JwtBackend::new(secret) panique sinon) :
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())),
];
Sur une route de tenant, les claims tenant et org_id du token doivent correspondre au tenant résolu, et
les tokens d'agent MCP (claim kind) sont refusés. Émettez avec le login JwtAuth ou
JwtBackend::issue_for_tenant ; les tokens de issue ne valent que sans tenant résolu.
Juste après un logout-all, émettez avec issue_for_user / issue_for_tenant_user :
un token de issue de cette seconde est refusé.
JwtBackend accepte les tokens d'accès émis par JwtLifecycle et refuse ses
tokens de rafraîchissement — les deux sont identiques sur le fil à typ près,
donc un token de rafraîchissement présenté comme bearer serait une
authentification valant des jours au lieu de quelques minutes.
La révocation est optionnelle et désactivée par défaut. Un JwtBackend nu
ne consulte jamais de liste noire : un token révoqué par /api/auth/logout
continue donc de s'authentifier via ce backend jusqu'à sa propre expiration.
Partagez un magasin entre le cycle de vie et le backend pour que la déconnexion
prenne effet :
use rustango::jti_store::{InMemoryJtiStore, JtiStore};
let shared: Arc<dyn JtiStore> = Arc::new(InMemoryJtiStore::new()); // Redis en production
let lifecycle = JwtLifecycle::new(secret.clone()).with_jti_store(Arc::clone(&shared));
let backend = JwtBackend::new(secret).with_jti_store(Arc::clone(&shared));
Ce doit être le même magasin. En câbler deux a l'air configuré et n'applique rien : la déconnexion écrit dans l'un et la vérification lit l'autre. Voir révocation et le magasin de JTI.
Écrivez un backend personnalisé en implémentant le trait (une seule méthode async
qui inspecte les Parts de la requête et renvoie Option<AuthUser>) :
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)
}
}
Verrouiller les routes : require_auth
RouterAuthExt ajoute le middleware. require_auth rejette les requêtes
anonymes avec un 401 ; optional_auth les laisse passer (de sorte qu'un
handler peut se ramifier selon connecté ou non) :
use rustango::tenancy::RouterAuthExt;
let app = Router::new()
.route("/profile", get(profile))
.require_auth(backends); // 401 if no backend matches
Ces méthodes prenaient un
Poolavant 0.57.11. Ce n'est plus le cas, et le changement est un correctif de sécurité, pas du rangement. Le pool était capturé à la construction du routeur et réutilisé pour chaque requête : un identifiant émis par un tenant s'authentifiait donc sur l'hôte d'un autre tenant — les backends cherchaient l'utilisateur dans la base avec laquelle le routeur avait été construit, etis_superuserpoursuivait son chemin dans une extension de requête sans nouvelle requête en base.Le pool vient désormais du tenant résolu pour chaque requête. La migration consiste à retirer l'argument :
.require_auth(backends, pool.clone()) → .require_auth(backends) .require_perm("post.add", pool) → .require_perm("post.add")Montez la couche de tenancy à l'extérieur de celles-ci. Sans contexte de tenant dans les extensions de requête, elles échouent en mode fermé avec un
500plutôt que de deviner une base.
Comportement vérifié :
// no credentials → 401
// Basic alice:<correct> → 200
// Basic alice:<wrong> → 401 (no backend accepted; no enumeration)
// Bearer <valid api key> → 200
Lire l'utilisateur : CurrentUser
Les handlers lisent l'utilisateur authentifié avec l'extracteur CurrentUser.
Il est infaillible — Some(user) lorsqu'un backend en a résolu un, None sinon :
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(),
}
}
Piège : parce que
CurrentUserest infaillible, oublierrequire_authne provoque pas d'échec de compilation — chaque requête voit simplementNone. Derrièrerequire_auth, les requêtes anonymes reçoivent déjà un401, doncusery est toujoursSome.
Permissions : require_perm
require_perm verrouille une route sur un codename de permission
({table}.{action}, par ex. post.add). Appliquez-le au sous-routeur interne et
require_auth à l'externe, afin que l'utilisateur soit résolu avant que la
permission ne soit vérifiée :
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)
Résolution : un superutilisateur (actif) passe tout ; un utilisateur
désactivé est refusé même avec des octrois ; une surcharge explicite par
utilisateur l'emporte sur les octrois de rôle ; sinon, tout rôle détenu par
l'utilisateur qui octroie le codename passe. Octroyez avec
set_user_perm_pool / les rôles via create_role_pool + assign_role_pool (les
tables de permissions sont créées par ensure_tables_pool).
ViewSet et les vues de template lisent le même utilisateur pour leurs
codenames, mais seulement sur tenant_router. Sur un .router(..) à pool fixe,
ils refusent l'utilisateur résolu par ces backends (403) : ce pool ne contient les utilisateurs d'aucun tenant.
Voir aussi
- Clés d'API et JWT — les identifiants que
ApiKeyBackend/JwtBackendconsomment. - Mots de passe — le hachage contre lequel
ModelBackendvérifie. - Décorateurs d'accès — verrouillage par handler
login_required/permission_required, l'alternative de style décorateur àrequire_auth/require_perm. - Sessions — authentification par cookie pour les navigateurs.
