Rustango docs
← Authentification

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.

Les backends d'authentification dans Rustango : une requête traverse une chaîne de backends (ModelBackend, ApiKeyBackend, JwtBackend) ; le premier à reconnaître l'identifiant l'emporte et injecte CurrentUser, puis require_perm vérifie un codename

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) et rustango::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

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 verrouillage 429 (ou 503 si le hachage des mots de passe est saturé), un jeton invalide 401 ;
  • si aucun ne correspond, la requête reçoit un 401 (avec require_auth) ou poursuit de manière anonyme (avec 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
];

Les backends intégrés

BackendIdentifiant qu'il litIdentifie un utilisateur par
ModelBackendAuthorization: Basic <base64(user:pass)>nom d'utilisateur + vérification du mot de passe argon2id contre rustango_users
ApiKeyBackendAuthorization: Bearer <prefix.secret>la table rustango_api_keys (voir Clés d'API)
JwtBackendAuthorization: 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 Pool avant 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, et is_superuser poursuivait 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 500 plutô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 CurrentUser est infaillible, oublier require_auth ne provoque pas d'échec de compilation — chaque requête voit simplement None. Derrière require_auth, les requêtes anonymes reçoivent déjà un 401, donc user y est toujours Some.


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 / JwtBackend consomment.
  • Mots de passe — le hachage contre lequel ModelBackend vé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.