Rustango docs
← Authentification

API d'authentification JWT

Le module JWT autonome signe et vérifie un seul token. Une vraie API a besoin de tout le cycle de vie : un token d'accès à courte durée, un token de rafraîchissement à longue durée, la rotation au rafraîchissement, et la révocation pour la déconnexion. Rustango fournit tout cela sous la forme de JwtLifecycle — et un routeur clé en main qui monte pour vous POST /api/auth/login, /refresh, /logout, et GET /me.

API d'authentification JWT : login émet une paire access+refresh, refresh effectue une rotation et met en liste noire l'ancien token, logout révoque via un magasin de JTI

Source : rustango::tenancy::jwt_lifecycle (JwtLifecycle, JwtTokenPair, JwtClaims) et rustango::tenancy::auth_routes (JwtAuth, Config) + rustango::jti_store (JtiStore, InMemoryJtiStore) — derrière jwt + tenancy.

Version exécutable : le moteur de tokens est couvert par le test auth_demo — cargo test -p auth_demo --test auth_jwt_api. Les endpoints HTTP sont cloisonnés par tenant et éprouvés de bout en bout par le propre crates/rustango/tests/tenant_auth_live.rs du framework.

Un terme vous est inconnu ? token d'accès/de rafraîchissement, rotation, révocation — voir le glossaire.

Complément approfondi de la section « Émettre et rafraîchir des JWT » du Guide de sécurité. Pour un token unique géré manuellement, voir plutôt JWT (autonome).


Table des matières


Le routeur intégré

JwtAuth::router() monte les quatre endpoints standard sur la table rustango_users propre à chaque tenant — les ~50 lignes de boilerplate de login que tout projet réécrit sinon :

MéthodeCheminCorps / AuthRenvoie
POST/api/auth/login{username, password}{access, refresh, user}
POST/api/auth/refresh{refresh}{access, refresh}
POST/api/auth/logoutAuthorization: Bearer <access> + {refresh} optionnel204 (révoque les deux JTI)
GET/api/auth/meAuthorization: Bearer <access>{user_id, username, is_superuser}

Login vérifie le mot de passe avec argon2id, puis émet une paire. Un mauvais mot de passe, un utilisateur inconnu et un compte inactif reçoivent tous le même 401 invalid credentials, donc l'endpoint ne révèle pas les comptes. Les logins partagent les limites de débit et le verrouillage de compte du login admin du tenant : au-delà de la limite la réponse est 429, et 503 quand le hachage des mots de passe est saturé. /me répond 403 pour un compte inactif. Les chemins, TTL et la clé de signature sont configurables via Config.

Le câblage

use axum::middleware::from_fn_with_state;
use rustango::tenancy::auth_routes::{require_bearer, Config, JwtAuth};

let auth = JwtAuth::new(Config::default());
rustango::manage::Cli::new()
    .tenancy()
    .api(my_app::urls::api()
        .layer(from_fn_with_state(auth.clone(), require_bearer)) // vos routes
        .merge(auth.router()))                                   // /api/auth/*
    .run()
    .await

Construisez un seul JwtAuth et passez-en des clones partout. Chaque instance a sa propre liste de révocation en mémoire : avec deux, un logout sur le routeur n'est pas vu par require_bearer, et le token reste valide jusqu'à son expiration. Un jti_store partagé (Redis, base de données) supprime aussi cette séparation.

require_bearer et /me n'acceptent que des tokens émis par /login ou /refresh, et les refusent dès que l'utilisateur se déconnecte n'importe où ou change de mot de passe.

Config::default() signe avec RUSTANGO_SESSION_SECRET (la même clé que le cookie de session admin, décodée du base64) et utilise des TTL de 15 min pour l'accès / 7 jours pour le rafraîchissement. JwtAuth::new panique quand la clé fait moins de 32 octets, donc un serveur mal configuré refuse de démarrer. Les champs de Config :

ChampDéfautRôle
prefix/api/authpréfixe d'URL des quatre endpoints
access_ttl_secs900durée de vie du token d'accès
refresh_ttl_secs7 joursdurée de vie du token de rafraîchissement
refresh_absolute_ttl_secs30 joursdurée maximale d'un login à travers les rafraîchissements ; doit être > 0
refresh_reuse_grace_secs10fenêtre de nouvel essai après une rotation ; 0 traite toute réutilisation comme un vol
refresh_per_minute30rafraîchissements par utilisateur et par minute dans ce processus ; au-delà un 429 ; 0 le désactive
session_secretNoneclé de signature explicite au lieu de RUSTANGO_SESSION_SECRET
jti_storeNonemagasin de révocation ; None est celui en mémoire
extra_claimsNonehook qui ajoute des claims aux deux tokens au login et à chaque rafraîchissement

extra_claims reçoit un ClaimsContext (user_id, username, is_superuser, tenant_slug). Renvoyer un nom réservé (sub, exp, jti, typ, kind) fait échouer le login en 500 ; tenant, pwf, sat et fam appartiennent au routeur. Avec la fonctionnalité config, Config::with_jwt_settings(&settings.auth.jwt) lit access_ttl_secs et refresh_ttl_secs depuis [auth.jwt] ; les clés issuer et audience y sont encore sans effet.

Les endpoints s'exécutent dans le contexte du tenant, montez-les donc dans une application tenancy. Pour un type de base tenant autre que celui par défaut, utilisez router_for::<DB>() et require_bearer_for::<DB>. auth.lifecycle() donne le JwtLifecycle sous-jacent, et auth.verify_for_tenant(bearer, &tenant) fait les mêmes contrôles que require_bearer et renvoie l'id utilisateur.

# Login → access + refresh
curl -sX POST localhost:8080/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"username":"alice","password":"hunter2hunter"}'

# Appeler un endpoint protégé
curl localhost:8080/api/auth/me -H "Authorization: Bearer $ACCESS"

Le moteur de tokens (JwtLifecycle)

Sous le routeur se trouve JwtLifecycle — utilisable directement si vous voulez le cycle de vie sans la forme HTTP intégrée :

use rustango::tenancy::jwt_lifecycle::JwtLifecycle;

let jwt = JwtLifecycle::new(secret_32_bytes);

// Login : émettre la paire.
let pair = jwt.issue_pair(user_id);
// → pair.access  (TTL court, à envoyer dans l'en-tête Authorization)
// → pair.refresh (TTL long, à stocker dans un cookie HttpOnly / stockage sécurisé)

// Requête authentifiée : vérifier le token d'accès.
match jwt.verify_access(&access).await {
    Some(claims) => { /* claims.sub est l'id utilisateur */ }
    None => { /* 401 : invalide, expiré, révoqué, ou mauvais type */ }
}

JwtLifecycle::new prend la clé en Vec<u8> et panique quand elle fait moins de 32 octets. Les TTL valent par défaut 15 min / 7 jours ; changez-les avec .with_access_ttl(secs) et .with_refresh_ttl(secs). issue_access_with(user_id, custom) émet un token d'accès seul, sans moitié de rafraîchissement, et blacklist_size() indique à peu près combien de JTI sont révoqués (0 pour un magasin qui ne sait pas compter).

Les tokens d'accès et de rafraîchissement ne sont pas interchangeables — verify_access rejette un token de rafraîchissement et vice versa, de sorte qu'un token d'accès à courte durée volé ne peut pas servir à en forger de nouveaux :

let pair = jwt.issue_pair(42);
assert!(jwt.verify_refresh(&pair.access).await.is_none());
assert!(jwt.verify_access(&pair.refresh).await.is_none());

Rafraîchissement et rotation

refresh échange un token de rafraîchissement valide contre une nouvelle paire et met en liste noire le JTI de l'ancien token de rafraîchissement — expiration glissante avec des tokens de rafraîchissement à usage unique (le rejeu de l'ancien est refusé) :

let pair = jwt.issue_pair(7);
let rotated = jwt.refresh(&pair.refresh).await.expect("refresh ok");
assert_ne!(pair.access, rotated.access);
assert!(jwt.refresh(&pair.refresh).await.is_none());   // l'ancien refresh est maintenant mort

Par défaut, refresh préserve les claims personnalisés du token. Si les permissions ont pu changer (rôle révoqué, portée réduite), utilisez refresh_with(token, new_claims) pour substituer un payload frais tout en mettant quand même en liste noire l'ancien JTI de rafraîchissement.

POST /api/auth/refresh ajoute trois contrôles : un changement de mot de passe depuis le login termine la chaîne, aucune chaîne ne dépasse Config::refresh_absolute_ttl_secs (30 jours) depuis le login, et rejouer un token déjà renouvelé révoque toute la chaîne. Une nouvelle tentative dans environ Config::refresh_reuse_grace_secs (10–20 s) après la rotation reçoit seulement un 401 : un client honnête qui a envoyé deux rafraîchissements reste connecté ; le prix est qu'un voleur dans cette fenêtre ne déclenche pas la révocation. La révocation ne vaut que ce que vaut le magasin de JTI (un magasin en mémoire oublie au redémarrage).


Révocation et le magasin de JTI

Chaque token porte un jti unique. revoke l'ajoute à une liste noire de sorte que les appels verify_* suivants échouent jusqu'à ce que le token ait de toute façon expiré — c'est ce qu'appelle POST /api/auth/logout. Il ne vérifie que la signature, donc il accepte aussi un token expiré, et il renvoie false pour un token qu'il ne peut pas vérifier :

let pair = jwt.issue_pair(1);
assert!(jwt.revoke(&pair.access).await);
assert!(jwt.verify_access(&pair.access).await.is_none());

Envoyez le token de rafraîchissement à /logout

Ne révoquer que le bearer met fin à un token qui aurait de toute façon expiré en quelques minutes. Le token de rafraîchissement est celui qui vit des jours, et il peut émettre de nouveaux tokens d'accès pendant toute sa TTL — une déconnexion qui le laisse en vie ne termine donc pas la session, elle la reporte :

POST /api/auth/logout
Authorization: Bearer <access>
{ "refresh": "<refresh>" }        // révoque aussi la moitié à longue durée

Le corps est optionnel, donc les clients écrits pour l'ancien endpoint continuent de fonctionner sans changement — ils révoquent simplement moins. Envoyez-le. Les deux moitiés sont rattachées au locataire appelant, de sorte qu'un sous-domaine ne peut pas révoquer le token d'un autre.

La liste noire réside dans un JtiStore interchangeable. Le InMemoryJtiStore par défaut est mono-processus et perd les révocations au redémarrage — convient pour une seule instance. Tout déploiement multi-réplica DOIT installer un magasin partagé et durable (Redis / BD) pour qu'une déconnexion sur une réplica soit honorée par toutes :

use rustango::jti_store::{InMemoryJtiStore, JtiStore};
use std::sync::Arc;

let shared: Arc<dyn JtiStore> = Arc::new(InMemoryJtiStore::new()); // à remplacer par Redis en prod
let a = JwtLifecycle::new(secret.clone()).with_jti_store(Arc::clone(&shared));
let b = JwtLifecycle::new(secret).with_jti_store(Arc::clone(&shared));

let pair = a.issue_pair(5);
a.revoke(&pair.access).await;
assert!(b.verify_access(&pair.access).await.is_none());   // B voit la révocation de A

Sans magasin partagé, /logout est au mieux « best-effort » : un token révoqué peut encore être accepté sur une autre réplica jusqu'à son expiration naturelle. C'est le paramètre de production le plus important pour l'authentification JWT.

Écrire un magasin durable

JtiStore est asynchrone (depuis v0.52) : une implémentation durable tient donc en une requête — pas de vidage en arrière-plan, pas de fenêtre de convergence pendant laquelle un jti révoqué est encore accepté ailleurs. Les deux méthodes renvoient JtiFuture<'_, T> (un future boxé — le trait est utilisé comme Arc<dyn JtiStore>, et un async fn natif dans un trait n'est pas compatible avec les objets dyn) :

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

impl JtiStore for PgJtiStore {
    fn is_used<'a>(&'a self, jti: &'a str) -> JtiFuture<'a, bool> {
        Box::pin(async move { self.lookup(jti).await })
    }

    fn mark_used<'a>(&'a self, jti: &'a str, exp_unix: i64) -> JtiFuture<'a, bool> {
        Box::pin(async move { self.insert_if_absent(jti, exp_unix).await })
    }
}

mark_used DOIT être atomique : parmi des appelants concurrents pour le même jti, exactement un doit obtenir true — une seule écriture conditionnelle (INSERT … ON CONFLICT DO NOTHING, Redis SET NX), jamais une lecture suivie d'une écriture. Sinon la garantie d'usage unique des tokens de rafraîchissement disparaît. Deux autres méthodes ont une valeur par défaut : approx_size (None, utilisée par blacklist_size) et is_process_local (false ; renvoyez true seulement pour un magasin qui ne partage pas les révocations, ce qui fait journaliser un avertissement par JwtAuth::new).

Comme la vérification consulte le magasin, verify_access, verify_refresh, refresh, revoke et les helpers de token MCP / tenant (mcp::verify_agent_token, tenancy::auth_routes::JwtAuth::verify_for_tenant) sont tous async. L'expiration est vérifiée avant le magasin : un token expiré ne coûte donc aucun aller-retour.


Claims personnalisés

Intégrez roles / tenant / scope directement dans le token pour que la vérification ne nécessite aucune consultation de BD. Les noms réservés (sub, exp, jti, typ) sont rejetés :

let custom = serde_json::json!({ "roles": ["admin"], "tenant": "acme" })
    .as_object().unwrap().clone();
let pair = jwt.issue_pair_with(99, custom)?;

let claims = jwt.verify_access(&pair.access).await.unwrap();
let roles: Vec<String> = claims.get_custom("roles").unwrap();   // ["admin"]

Les claims personnalisés survivent à refresh (reportés sur la nouvelle paire) sauf si vous utilisez refresh_with.


Notes et limites

  • Sessions vs JWT vs ceci : un JWT simple ne peut pas être révoqué ; une Session est révocable mais nécessite une consultation du magasin à chaque requête ; JwtLifecycle est la voie intermédiaire — vérification sans état, plus une liste de blocage JTI pour les révocations dont vous avez réellement besoin (déconnexion, rotation).

  • Les endpoints HTTP sont cloisonnés par tenant. JwtAuth::router() résout les utilisateurs via le contexte du tenant + rustango_users ; montez-le dans une application .tenancy(). Le moteur de tokens (JwtLifecycle) lui-même n'a pas cette exigence.

  • Associez ceci au JwtBackend de la chaîne de backends d'authentification pour authentifier des routes arbitraires à partir de l'en-tête Authorization: Bearer.

  • Signature HS256, plancher de clé de 32 octets — même algorithme et mêmes contraintes que le JWT autonome.

  • Les jetons sont de vrais JWT, donc tout ce qui vérifie un JWT peut vérifier ceux-ci : jwt.io, la bibliothèque standard de votre plateforme, une passerelle d'API, un autre service auquel vous confiez un jeton. Trois segments, un en-tête JOSE {"alg":"HS256","typ":"JWT"}, signé sur header.payload.

    Avant 0.57.5, c'étaient deux segments sans en-tête, signés sur la seule charge utile — lisibles par rien d'autre que rustango, et rejetés jusque par rustango::jwt::decode. Si vous aviez écrit un vérificateur maison pour contourner cela, vous pouvez le jeter.

    Depuis 0.62.0, un jeton en deux segments est refusé, par JwtLifecycle comme par JwtBackend.


Voir aussi