Rustango docs
← Guides

Guide de sécurité

Ce guide couvre chaque fonctionnalité de sécurité fournie par Rustango et la manière de les combiner. Si vous avez déjà utilisé un framework web, la plupart vous sembleront familières — les noms diffèrent, mais les idées sont les mêmes. Chaque fonctionnalité ci-dessous se met généralement en place en une seule ligne. Quand vous êtes prêt à déployer, lancez manage check --deploy pour un audit automatisé.

La pile de middleware renforcée câblée dans une seule chaîne : identifiants de requête, journalisation des accès, limitation de débit, CORS et en-têtes de sécurité

Table des matières


La checklist de défense en profondeur

Une bonne sécurité vient de nombreuses petites couches, pas d'un seul grand mur. Une application Rustango en production devrait empiler les couches ci-dessous — la plupart tiennent en une ligne chacune. Le reste de ce guide explique chacune d'elles.

let app = Router::new()
    .route("/...", ...)
    .merge(health::health_router(pool.clone()))         // /health, /ready
    .request_id(RequestIdLayer::default())              // log correlation
    .access_log(AccessLogLayer::default())              // PII-redacted by default
    .rate_limit(RateLimitLayer::per_ip(60, ONE_MIN))    // 60 req/min/IP
    .cors(CorsLayer::new().allow_origins(vec!["..."])) // explicit allowlist
    .security_headers(                                   // HSTS + XFO + nosniff + Referrer + CSP
        SecurityHeadersLayer::strict()
            .csp(CspBuilder::strict_starter().build()),
    );
// Plus: TLS termination at reverse proxy.
// Plus: argon2 for passwords, JWT lifecycle for tokens, TOTP for MFA.

Les tenants à préfixe de chemin partagent une origine avec la console opérateur : voir Noms d'hôte. En production, préférez un hôte par tenant.


Définir les en-têtes de sécurité

Les en-têtes de sécurité indiquent au navigateur comment protéger vos utilisateurs (bloquer le clickjacking, forcer HTTPS, empêcher le sniffing de type de contenu). SecurityHeadersLayer définit l'ensemble standard en une ligne — les en-têtes de protection habituels, sans avoir à les nommer un par un. (Une « couche » est le terme de Rustango pour désigner un middleware ; vous l'attachez à votre routeur.)

À approfondir : Middleware couvre le fonctionnement des couches, leur ordre, le catalogue intégré complet et la rédaction de vos propres couches (sensibles à la locale, au fuseau horaire, en-têtes, CSRF).

use rustango::security_headers::{SecurityHeadersLayer, SecurityHeadersRouterExt, CspBuilder};

let app = router.security_headers(SecurityHeadersLayer::strict());

Presets

PresetQuand l'utiliser
strict()Production : HSTS preload + XFO=DENY + nosniff + Referrer-Policy=same-origin + COOP=same-origin + Permissions-Policy verrouillée
relaxed()Intégrable dans des iframes : SAMEORIGIN + HSTS 1 an
dev()Local : nosniff uniquement (pas de HSTS pour éviter de verrouiller localhost en HTTPS pour toujours)
empty()Construire à partir de zéro

SecurityHeadersLayer::default() vaut strict(). from_preset(name) choisit un préréglage par son nom ("strict", "relaxed", "dev", "none" ou "empty") ; un nom inconnu donne strict(), jamais aucun en-tête. from_settings(&settings.security) lit [security] headers_preset, csp et hsts_max_age_secs (0 désactive HSTS). Un en-tête déjà posé par le handler est conservé.

Deux autres couches ont leur place ici. host_validation::AllowedHostsLayer::new(["example.com", ".example.com"]) répond 400 à une requête dont le Host n'est pas listé (.example.com couvre aussi ses sous-domaines). ssl_redirect::SslRedirectLayer::new() répond au HTTP simple par un 301 vers HTTPS ; derrière un proxy qui termine TLS, ajoutez .proxy_ssl_header("X-Forwarded-Proto", "https"), sinon il redirige en boucle.

CSP personnalisé

let csp = CspBuilder::new()
    .default_src(&["'self'"])
    // The placeholder becomes a per-request nonce only under CspNonceLayer (below).
    .script_src(&["'self'", "'nonce-__RUSTANGO_NONCE__'", "https://cdn.example.com"])
    .style_src(&["'self'", "'nonce-__RUSTANGO_NONCE__'"])
    .img_src(&["'self'", "data:", "https:"])
    .font_src(&["'self'", "data:"])
    .connect_src(&["'self'", "wss://realtime.example.com"])
    .frame_ancestors(&["'none'"])                 // disallow embedding (clickjacking)
    .object_src(&["'none'"])
    .directive("base-uri", &["'self'"])
    .build();

let layer = SecurityHeadersLayer::strict().csp(csp);

'nonce-__RUSTANGO_NONCE__' (la constante csp_nonce::CSP_NONCE_PLACEHOLDER) n'est qu'un placeholder. Montez csp_nonce::CspNonceLayer::default() avec .csp_nonce(...) après .security_headers(...), pour qu'il s'exécute à l'extérieur : il crée un nonce aléatoire par requête, le place dans la requête comme Extension<Nonce> et remplace le placeholder dans l'en-tête CSP. Sans lui, le navigateur reçoit le placeholder littéral et bloque chaque script et style inline.

Les pages d'erreur intégrées et les templates de l'admin mettent le même nonce sur leurs balises inline, elles passent donc cette politique.

Déploiement progressif du CSP

Utilisez csp_report_only pour surveiller sans casser la production :

let layer = SecurityHeadersLayer::strict()
    .csp(CspBuilder::strict_starter().build())
    .csp_report_only(true);                       // sends Content-Security-Policy-Report-Only

Après avoir vérifié l'absence d'erreurs dans la console → basculez csp_report_only(false) pour appliquer.


Autoriser les requêtes cross-origin (CORS)

Le CORS contrôle quels autres sites web sont autorisés à appeler votre API depuis un navigateur. Par défaut, les navigateurs bloquent ces appels ; vous réautorisez spécifiquement certaines origines. Listez vos vrais domaines front-end en production et ne l'ouvrez jamais à tout le monde.

use rustango::cors::{CorsLayer, CorsRouterExt};

// Production
let layer = CorsLayer::new()
    .allow_origins(vec!["https://app.example.com", "https://admin.example.com"])
    .allow_methods(vec!["GET", "POST", "PUT", "PATCH", "DELETE"])
    .allow_headers(vec!["content-type", "authorization"])
    .allow_credentials(true)
    .max_age(Duration::from_secs(3600));

// Dev only
let layer = CorsLayer::permissive();              // any origin, common methods

CorsLayer::new() n'autorise aucune origine tant que vous n'en ajoutez pas. CorsLayer::from_settings(&settings.security) lit [security] cors_allowed_origins : une liste vide donne None (ne rien monter), "*" donne permissive(), et des origines nommées donnent une liste d'autorisation avec les méthodes courantes (QUERY compris) et les en-têtes de requête Content-Type, Authorization, X-Date, Idempotency-Key, If-Match, If-None-Match. Les deux exposent Retry-After, Idempotent-Replayed, ETag, Location, Link aux scripts. cors_allowed_headers et cors_expose_headers s'ajoutent à ces listes, et cors_allow_credentials = true envoie Access-Control-Allow-Credentials avec des origines nommées ; avec "*" il est refusé avec une erreur dans les logs, et une entrée d'en-tête "*" est ignorée.

Note de sécurité : avec des identifiants, vous DEVEZ lister des origines explicites. allow_credentials(true) combiné à allow_any_origin() ne donne pas un CORS joker avec identifiants — cela n'existe pas, et le demander ne vous donne aucune des deux moitiés.

Rustango répond alors Access-Control-Allow-Origin: * et aucun en-tête Access-Control-Allow-Credentials, si bien que le navigateur bloque la requête avec identifiants. Dans les anciennes versions, l'origine demandeuse était renvoyée en écho — ce que les navigateurs acceptent justement avec des identifiants : cette combinaison était un trou bien réel, lisible par n'importe quel site visité par l'utilisateur, et cette page le décrivait comme quelque chose que le navigateur rejetterait.

Utilisez .allow_origins([...]) avec les origines que vous servez réellement. Ce chemin est inchangé et envoie toujours Access-Control-Allow-Credentials: true.


Limiter le débit des requêtes

La limitation de débit plafonne le nombre de requêtes qu'un client peut effectuer dans une fenêtre de temps. Utilisez-la pour ralentir les connexions par force brute, le scraping et les abus. Vous pouvez limiter par IP, par clé d'API ou globalement pour un endpoint coûteux.

use rustango::rate_limit::{RateLimitLayer, RateLimitRouterExt};

// Per-IP
router.rate_limit(RateLimitLayer::per_ip(60, Duration::from_secs(60)));

// Per-API-key (header)
router.rate_limit(RateLimitLayer::per_header("authorization", 1000, Duration::from_secs(3600)));

// Global ceiling for an expensive endpoint
router.rate_limit(RateLimitLayer::global(10, Duration::from_secs(1)));

En cas d'épuisement : 429 Too Many Requests avec l'en-tête Retry-After. Chaque réponse réussie inclut X-RateLimit-Limit + X-RateLimit-Remaining. La couche est un seau à jetons : capacity requêtes, rechargées sur refill_period. Elle garde au plus 100 000 seaux ; changez-le avec .max_buckets(n).

Derrière un reverse proxy, nommez vos proxys ou per_ip ne limite rien d'utile. RateLimitLayer::per_ip s'indexe sur le socket de connexion, qui derrière un proxy est l'adresse du proxy — donc tous les clients partagent un seul compartiment. Un seul client bruyant limite alors tous les autres, et aucun attaquant individuel n'est jamais limité.

Montez RealIpLayer et dites-lui à quels sauts croire :

use rustango::real_ip::{HeaderStrategy, RealIpLayer, RealIpRouterExt};

app.rate_limit(RateLimitLayer::per_ip(60, Duration::from_secs(60)))
   .real_ip(
       RealIpLayer::new(HeaderStrategy::XForwardedFor)
           .trust_proxies(["10.0.0.0/8"])?,   // votre ingress, pas Internet
   );

L'ordre est déterminant et échoue en silence. Les couches s'appliquent de l'extérieur en dernier : real_ip doit donc être ajouté après rate_limit pour s'exécuter avant. Dans l'autre sens, le limiteur ne voit aucune adresse résolue et s'indexe de nouveau silencieusement sur le socket — il avertit une fois lorsqu'un en-tête de transfert arrive sans adresse résolue.

trust_proxies n'est pas une décoration facultative. X-Forwarded-For est défini par celui qui l'envoie. Sans liste de proxys déclarée, l'en-tête n'est qu'une affirmation : le limiteur l'ignore entièrement et s'indexe sur le socket — délibérément. Sinon, n'importe quel client pourrait se forger un compartiment neuf à chaque requête en variant un en-tête, transformant « la limite est trop grossière » en « il n'y a pas de limite ». RealIp (l'affirmation) convient pour la journalisation ; seul TrustedRealIp, présent quand le pair correspond à trust_proxies, indexe un limiteur.

Une règle pour chaque lecteur d'IP. Limites de débit, throttles de ViewSet, limites de connexion, signaux d'auth et journal d'accès utilisent la même adresse : TrustedRealIp (lire X-Forwarded-For de droite à gauche, prendre le premier saut hors de trust_proxies), sinon le socket. Aucun ne lit le saut le plus à gauche : c'est le client qui l'écrit.

Nommez les adresses depuis lesquelles votre ingress se connecte réellement. Faire confiance à une plage plus large offre le contournement à quiconque s'y trouve.

Limites de connexion intégrées

Chaque connexion par mot de passe intégrée (admin, console opérateur, admin de tenant, JWT /auth/login) passe par rustango::login_throttle avant la recherche de l'utilisateur. Il vérifie, dans l'ordre, un verrou par nom d'utilisateur (5 échecs, 15 min) qui compte les noms inconnus comme les vrais, une limite par IP (20 connexions échouées/min ; en IPv6, par /64) et une limite globale par point de connexion (600 connexions échouées/min chacun pour l'admin, la console opérateur et chaque tenant). Une connexion réussie ne compte pas dans les limites. Un nom d'utilisateur qui s'est connecté depuis une IP au cours des 30 derniers jours passe outre une limite globale épuisée depuis cette IP, pour qu'une attaque depuis de nombreuses IP ne puisse pas verrouiller tous les utilisateurs. Depuis cette IP, il compte aussi sur son propre verrou par nom d'utilisateur, de sorte que les mauvais mots de passe d'un autre client ne le verrouillent pas ; sa limite par IP s'applique toujours. Une fois la ligne utilisateur trouvée, le verrou suit aussi le nom d'utilisateur stocké, de sorte que les graphies que la base considère égales (MySQL fait correspondre alicé à alice) partagent un même verrou. HTTP Basic et les clés d'API ont leur propre portée et ne comptent que les échecs. Une connexion refusée reçoit 429 avec Retry-After, et la même réponse que le compte existe ou non.

Derrière un reverse proxy, montez RealIpLayer avec vos proxys comme ci-dessus ; une application Cli appelle plutôt Cli::with_trusted_proxies(["127.0.0.1/32"])?. Sans cela, chaque client a l'adresse du proxy et partage un seul compartiment par IP ; un avertissement est journalisé une fois quand des en-têtes de transfert arrivent.

Le hachage des mots de passe exécute au plus une tâche par CPU, partagée par toutes les connexions ; HTTP Basic, les clés d'API et les secrets d'agent peuvent utiliser au plus la moitié des créneaux. Une connexion qui attend un créneau plus de hash_wait_ms (5 s) reçoit 503 avec Retry-After, pour les utilisateurs connus comme inconnus.

Réglez-les sous [auth] : login_ip_limit, login_ip_window_secs, login_global_limit, login_global_window_secs, lockout_threshold, lockout_duration_secs, hash_wait_ms. Une valeur définie dans le code (login_throttle::configure_shared, account_lockout::configure_shared, passwords::configure_hash_wait) l'emporte sur ces clés. Les compartiments par IP et global sont propres au processus, sauf si vous installez login_throttle::configure_shared(LoginThrottle::with_cache(limits, cache)), qui les compte par fenêtres fixes dans un cache partagé (en cas d'erreur du cache, les deux retombent sur le processus ; une rafale à cheval sur une limite de fenêtre peut atteindre deux fois une limite ; des applications partageant un cache partagent les compteurs, sauf si chacune utilise son propre ScopedCache) ; la première connexion journalise un avertissement tant qu'ils sont propres au processus. Le verrou par nom d'utilisateur utilise account_lockout::shared(), que vous pouvez adosser à un cache partagé via account_lockout::configure_shared. Les échecs sont comptés dans une fenêtre fixe (1 heure par défaut) qui commence au premier échec : un attaquant dispose donc de lockout_threshold - 1 essais par fenêtre sans verrou ; les limites par IP et globale bornent le reste. Les clés [auth] sont appliquées par manage::Cli quand il charge les réglages ; une app qui construit server::Builder sans lui appelle plutôt les fonctions.

Champ de connexion. Les utilisateurs d'un tenant se connectent avec leur nom d'utilisateur, sauf avec [auth] login_field = "email" (ou Cli::login_field(LoginField::Email) / server::Builder::login_field, qui l'emportent sur la clé). L'e-mail demande la feature sso, qui ajoute la colonne email. L'e-mail est comparé sans tenir compte de la casse sur chaque backend, dans le formulaire de connexion du tenant (libellé « Email »), en HTTP Basic et sur /auth/login ({"username": …} ou {"email": …}), et le verrou de connexion ci-dessus suit l'e-mail enregistré. Chaque utilisateur a besoin de son propre e-mail : un utilisateur sans e-mail ne peut pas se connecter, et un e-mail que deux utilisateurs partagent (casse ignorée) ne connecte aucun des deux. Le serveur journalise au démarrage chaque tenant qui a de tels utilisateurs ; il avertit au lieu de refuser de démarrer, pour que les données d'un tenant ne bloquent pas tous les tenants. create-user --email le définit.

RateLimitLayer est local au processus — il compte les requêtes uniquement au sein d'une instance en cours d'exécution, ce qui convient si vous exécutez une seule instance. Si vous exécutez plusieurs instances (répliques) derrière un load balancer, chacune tiendrait son propre compte, et la limite réelle se multiplierait. Pour partager un seul compte entre toutes les répliques, utilisez rate_limit_cache::CacheRateLimitLayer, qui délègue à n'importe quelle implémentation de cache::Cache (à associer avec cache::RedisCache pour un compteur partagé incrémenté de façon atomique par le INCRBY de Redis) :

use rustango::cache::RedisCache;
use rustango::rate_limit::KeyBy;
use rustango::rate_limit_cache::{CacheRateLimitLayer, CacheRateLimitRouterExt};

let cache: rustango::cache::BoxedCache =
    std::sync::Arc::new(RedisCache::new("redis://localhost").await?);

let app = axum::Router::new()
    .route("/api/login", axum::routing::post(login))
    .cache_rate_limit(
        CacheRateLimitLayer::new(cache, 5, Duration::from_secs(60))
            .key_by(KeyBy::Ip)
            .key_prefix("login"),
    );

Il compte par fenêtres fixes, donc une rafale à cheval sur une limite de fenêtre peut atteindre le double de la limite. Une erreur de cache laisse passer la requête (fail open) et journalise un avertissement.

Keyer sur un en-tête secret est sûr à partager. Avec key_by(KeyBy::Header("authorization")) ou "x-api-key", le limiteur adossé au cache hache la valeur de l'en-tête avant de l'utiliser comme clé : un Redis partagé ne stocke donc jamais une crédential vivante là où quelqu'un lisant les clés pourrait la récolter. KeyBy::Ip nécessite ConnectInfo (ou un RealIpLayer avec trust_proxies en amont) ; sans cela, le limiteur avertit une fois et retombe sur un unique bucket partagé.

key_by(KeyBy::Tenant) donne à chaque tenant son propre bucket, par id d'org, si bien qu'un tenant très actif n'épuise pas le quota d'un autre ; KeyBy::Global reste un bucket unique pour toute la plateforme. Montez-le sur les routes du tenant : en dehors, toutes les requêtes partagent un bucket.


Autoriser ou bloquer des IP

Verrouillez les routes sensibles (comme votre admin) à un ensemble connu d'adresses IP, ou bloquez des abuseurs spécifiques. Une liste d'autorisation ne permet que les réseaux listés ; une liste de blocage refuse ceux qui sont listés.

use rustango::ip_filter::{IpFilterLayer, IpFilterRouterExt};

// Internal admin only
let admin_router = admin_router
    .ip_filter(IpFilterLayer::allow_only(vec![
        "10.0.0.0/8",
        "192.168.0.0/16",
        "203.0.113.0/24",
    ])?);

// Block known abusers
let public_router = public_router
    .ip_filter(IpFilterLayer::block(vec!["203.0.113.42"])?);

IPv4 + IPv6 pris en charge. Sûr entre familles (un CIDR IPv4 ne correspond pas aux adresses IPv6). Renvoie 403 Forbidden en cas de rejet.

Important : Rustango lit l'IP client depuis ConnectInfo<SocketAddr>. Montez avec :

axum::serve(listener, app.into_make_service_with_connect_info::<SocketAddr>()).await?;

Une requête sans ConnectInfo est refusée par allow_only et acceptée par block ; changez cela avec .allow_no_ip(bool). Derrière un reverse proxy, le pair est le proxy. Appelez .behind_trusted_proxy() pour vérifier plutôt l'IP client qu'un RealIpLayer avec trust_proxies a résolue. Le filtre doit se trouver à l'intérieur de ce RealIpLayer (ajoutez .real_ip(...) après .ip_filter(...)), sinon il vérifie l'adresse du proxy et une liste de blocage laisse passer tout le monde. ip_filter ne lit jamais lui-même un en-tête de transfert.


Se protéger contre le CSRF

CSRF et API à jeton. Le CSRF protège les requêtes authentifiées par cookie. Une API purement à jeton / Bearer / JWT n'est pas une cible CSRF — n'appliquez pas la couche CSRF sur celle-ci (sinon vous renverrez des 403 à des clients légitimes). Pour une SPA qui utilise bien des cookies, lisez le cookie rustango_csrf et renvoyez-le dans l'en-tête X-CSRF-Token.

Le CSRF (cross-site request forgery) survient lorsqu'un autre site trompe le navigateur d'un utilisateur connecté pour lui faire soumettre une requête à votre application. La défense est un jeton secret sur chaque formulaire, que le serveur revérifie à chaque écriture. Le middleware CSRF vit dans rustango::forms::csrf (derrière la feature csrf, activée automatiquement par la feature admin) :

use rustango::forms::csrf;

let app = Router::new()
    .route("/contact", get(form).post(submit))
    .layer(csrf::layer());

csrf::layer() prend le flag Secure du cookie dans session::secure_cookies() : la politique de démarrage ([security] secure_cookies, que le chemin manage met à true par défaut), sinon Secure sur le tier prod. Les CBV template_views émettent leur cookie via forms::csrf::ensure_token, qui suit la même politique. csrf::with_config(CsrfConfig) utilise plutôt CsrfConfig::secure (défaut true) ; sur http://localhost, appelez CsrfConfig::default().allow_insecure_for_dev(), sinon le navigateur rejette le cookie et chaque POST reçoit 403. with_config fixe aussi les noms de cookie/en-tête et trusted_origins — des origines supplémentaires admises en plus du Host de la requête (.trust_origin("https://app.example.com"), jokers *.example.com acceptés). La vérification d'Origin s'exécute même si la liste est vide : un Origin étranger reçoit 403, et en TLS un POST sans Origin aussi. Dans les templates, {{ csrf_token }} vous donne le jeton brut et {{ csrf_input }} un <input> caché prêt à l'emploi — écrivez-le {{ csrf_input | safe }}, car Tera échappe automatiquement les templates .html : sans le filtre, la page affiche un <input …> littéral visible, le formulaire ne porte aucun champ _csrf et chaque POST renvoie 403. Les deux variables ne sont dans le contexte que pour les CBV template_views, ou après avoir appelé vous-même forms::csrf::stamp_into_context — un handler écrit à la main n'a ni l'une ni l'autre. Il utilise le motif du cookie à double soumission. GET, HEAD, OPTIONS et TRACE sont sûres, ainsi que QUERY sauf si require_csrf_on_query est activé. Sur toute autre méthode, la couche vérifie l'en-tête X-CSRF-Token (ou le champ de formulaire _csrf) par rapport au cookie rustango_csrf ; une discordance renvoie 403 Forbidden.

Exempter les endpoints collecteurs. CsrfConfig::exempt_prefix("/path") (répétable) ignore l'application du CSRF pour les méthodes non sûres sur les requêtes dont le chemin commence par le préfixe donné. Ceci concerne les endpoints append-only, sans état d'authentification, atteints via navigator.sendBeacon — par exemple un collecteur d'analytics — qui ne peuvent pas définir un en-tête X-CSRF-Token et, lorsque la page est servie depuis un cache CDN qui supprime Set-Cookie, peuvent ne porter aucun cookie CSRF du tout. Gardez les préfixes étroits et n'exemptez jamais quoi que ce soit qui lit ou écrit un état d'authentification.

Avec la fonctionnalité mcp, Cli::with_csrf() et with_csrf_config() exemptent eux-mêmes les endpoints MCP : {prefix}, {prefix}/token et {prefix}/oauth/token pour le [mcp] prefix (par défaut /mcp), rien d'autre en dessous. Les clients MCP n'envoient pas de cookie CSRF. Le routeur tenant y vérifie un jeton d'agent ; le mcp::router(pool) mono-base n'en vérifie aucun, placez donc votre propre authentification devant. Un préfixe / n'exempte rien et journalise un avertissement. L'exemption s'applique même sans routeur MCP monté, et le démarrage journalise un avertissement qui nomme les chemins : n'y placez aucune route authentifiée par cookie.

L'auto-admin. Dès que vous appelez .with_session_auth(...), le CSRF est monté automatiquement sur chaque mutation de l'admin — création, modification, suppression, actions groupées, purge d'audit — et chaque formulaire de l'admin rend son jeton pour vous. Il n'y a rien à câbler et aucun moyen de s'y soustraire.

La condition est délibérée, pas fortuite : le CSRF défend des identifiants que le navigateur joint de lui-même, c'est donc le cookie de session qui lui donne un sens. Un admin construit sans with_session_auth n'a aucun identifiant géré par rustango à usurper, et ses mutations sont directement joignables par quiconque atteint la route — c'est un trou d'authentification, pas de CSRF, et le CSRF ne le réduirait pas. Cela ne vaut que tant que rien devant n'est un identifiant joint par le navigateur. HTTP Basic (protect_with_basic_auth) ou votre propre auth par cookie en est un, donc les POST cross-site s'en servent — et monter csrf::layer() vous-même ne règle rien, car l'admin ne rend les jetons de formulaire qu'avec with_session_auth, donc chaque POST renvoie 403. Utilisez with_session_auth pour un admin de navigateur.

Dans les anciennes versions, ce paragraphe affirmait que la protection était inconditionnelle alors que la seule route protégée était POST /login. Toute autre mutation de l'admin acceptait un POST inter-sites porté par la session de l'administrateur — y compris la purge d'audit, si bien que la même classe de requête pouvait effacer sa propre trace.


Prévenir le XSS

Le XSS (cross-site scripting) survient lorsqu'une entrée utilisateur est rendue en HTML et s'exécute comme du code dans le navigateur de quelqu'un d'autre. La solution est d'échapper toute entrée utilisateur avant qu'elle n'atteigne la page. Rustango gère cela de deux façons :

1. Auto-échappement des templates Tera — Tera est le moteur de templates de Rustango. Chaque {{ var }} est automatiquement échappé en HTML dans chaque template que construit le framework, quelle que soit son extension. template_extensions::html_tera() / html_tera_from_glob(glob) donnent la même chose à votre propre moteur ; un Tera::new nu n'échappe que .html, .htm et .xml. Seules les parties texte des e-mails (sujet et corps .txt d'EmailRenderer) sont rendues brutes. Utilisez {{ var | safe }} pour vous en soustraire — rare, et dangereux, donc ne le faites que pour du HTML auquel vous faites entièrement confiance.

2. Fonction d'échappement manuelle — pour quand vous construisez du HTML dans du code Rust au lieu d'un template :

use rustango::text::html_escape;

let safe = html_escape(user_input);
// "<script>" → "&lt;script&gt;"
// "a & b" → "a &amp; b"

Remplace &, <, >, ", '. Convient pour le contenu d'éléments HTML + les attributs entre guillemets doubles.

Pour une défense XSS basée sur le CSP, voir Définir les en-têtes de sécurité.


Prévenir l'injection SQL

L'injection SQL survient lorsqu'une entrée utilisateur est collée directement dans une chaîne SQL et modifie la requête. L'ORM de Rustango empêche cela par conception : il utilise partout le binding de paramètres de sqlx — chaque valeur est envoyée comme un placeholder lié ($1, $2, ... sur PostgreSQL, ? sur MySQL et SQLite), jamais collée dans le texte de la requête. (sqlx est la bibliothèque de base de données sous-jacente.) Vous ne pouvez pas accidentellement concaténer une entrée utilisateur dans du SQL via l'API de l'ORM.

Il y a deux endroits où rester vigilant :

1. Les noms de table et de colonne dans les actions groupées :

Les placeholders protègent les valeurs, mais ils ne peuvent pas porter un identifiant (un nom de table ou de colonne), donc ceux-ci ont besoin de leur propre garde-fou. Les actions groupées de l'admin et de ListView écrivent via l'ORM, donc aucun nom brut n'atteint le SQL. Chaque clé sélectionnée est lue avec le type de la clé primaire du modèle, et une clé du mauvais type est refusée. Ce garde-fou s'exécute pour vous — vous ne l'appelez pas vous-même.

2. L'échappatoire du SQL brut :

Si vous descendez au niveau de sqlx brut, liez chaque valeur comme un paramètre et ne collez jamais un identifiant (nom de table ou de colonne) provenant d'une entrée utilisateur dans la chaîne de requête — les placeholders ne peuvent pas porter d'identifiants :

// ✅ values go through bound placeholders
sqlx::query("SELECT * FROM posts WHERE id = $1")
    .bind(1).fetch_all(&pool).await?;

// ❌ NEVER interpolate a user-supplied identifier into the SQL string
let sql = format!("SELECT * FROM \"{user_table}\" WHERE id = $1");
sqlx::query(&sql).bind(1).fetch_all(&pool).await?;

Authentifier les utilisateurs

L'authentification est la manière dont vous confirmez qui effectue une requête. Rustango fournit trois backends prêts à l'emploi (Basic auth, clés d'API et JWT) et vous laisse écrire les vôtres en implémentant un seul trait. Vous les attachez aux routes, et les requêtes sans identifiant reconnu reçoivent un 401.

SSO admin. Pour permettre aux opérateurs de se connecter à l'admin avec un IdP externe (Google, Microsoft/Azure AD, GitHub, ou tout fournisseur OpenID Connect) au lieu d'un mot de passe, activez la feature admin-sso — voir le guide SSO. Les fournisseurs sont gérés depuis l'interface admin sous forme de lignes (plusieurs par surface ; par tenant, ou un ensemble partagé entre tenants), avec le secret client chiffré au repos. Il connecte le compte lié au subject de l'IdP (la liaison par email est optionnelle par fournisseur et ne s'applique jamais aux superusers ni au staff ; le bare admin n'inscrit jamais personne, un fournisseur de l'admin de tenant seulement selon son signup_mode) et réutilise la session existante.

Trois backends prêts à l'emploi

use rustango::tenancy::auth_backends::{ModelBackend, ApiKeyBackend, JwtBackend};
use rustango::tenancy::middleware::{RouterAuthExt, CurrentUser};
use std::sync::Arc;

let backends = vec![
    Arc::new(ModelBackend) as _,                   // Authorization: Basic <b64>
    Arc::new(ApiKeyBackend) as _,                   // Authorization: Bearer <prefix>.<secret>
    Arc::new(JwtBackend::new(secret)) as _,         // Authorization: Bearer <jwt>
];

// `require_auth` / `require_perm` are `Router::layer` calls: each wraps the
// routes registered BEFORE it. Chaining them on one router would put /me
// behind post.add. Gate the permission on an inner sub-router instead.
let posts = Router::new()
    .route("/posts/new", post(create_post))
    .require_perm("post.add");     // inner: needs the codename

let app = Router::new()
    .route("/me", get(profile))
    .merge(posts)
    .require_auth(backends);       // outer: resolves the user first

Le middleware essaie chaque backend dans l'ordre. Le premier qui réussit l'emporte ; le premier qui renvoie une erreur dure arrête la chaîne. require_perm répond 401 sans utilisateur, 403 sans le codename et 503 quand la lecture de la permission échoue. optional_auth(backends) résout l'utilisateur de la même façon mais laisse passer les requêtes anonymes. Les trois exigent la couche tenancy montée à l'extérieur ; sans TenantContext, elles échouent de façon sûre avec 500.

Écrire votre propre backend

use rustango::tenancy::auth_backends::{AuthBackend, AuthUser, AuthError};
use async_trait::async_trait;

pub struct OAuthBackend { /* ... */ }

#[async_trait]
impl AuthBackend for OAuthBackend {
    async fn authenticate(&self, parts: &Parts, pool: &rustango::sql::Pool)
        -> Result<Option<AuthUser>, AuthError>
    {
        // Read your custom header, validate, look up the user
        Ok(None)  // means: not my request, try next backend
    }
}

Hacher et vérifier les mots de passe

Ne stockez jamais les mots de passe en clair. Hachez-les à l'inscription avec hash, et à la connexion comparez la tentative avec verify. Utilisez strength_score pour rejeter les mots de passe faibles avant même de les hacher.

use rustango::passwords::{hash, verify, strength_score, StrengthIssue};

// Signup
let issues = strength_score(&new_password);
if !issues.is_empty() {
    return Err(format!("password too weak: {issues:?}"));
}
let hashed = hash(&new_password)?;

// Login
let ok = verify(&attempted, &user.password_hash)?;

hash et verify bloquent le thread pendant tout le hachage. En code async, utilisez hash_async / verify_async, qui tournent sur le pool de hachage borné et renvoient PasswordError::Busy quand aucun slot ne se libère à temps. Après une connexion réussie, needs_rehash(stored) indique que le hachage est sous le coût actuel ; rehash_async donne le nouveau.

Le hachage utilise argon2id (le défaut recommandé par l'OWASP depuis 2023 — il résiste mieux au cassage par GPU que bcrypt). Les hachages sont stockés au format PHC-string, de sorte que vous pouvez changer les paramètres plus tard sans casser les anciens hachages.

La vérification de robustesse intégrée est intentionnellement minimale. Pour les déploiements sérieux, vérifiez aussi les mots de passe par rapport à l'API HIBP / pwned-passwords afin de rejeter ceux connus comme divulgués.

À approfondir : Mots de passe — internals d'argon2id, salage automatique, connexions résistantes aux attaques temporelles (verify_dummy), et où vit le hachage. Une fois authentifié, passez la main à une Session (navigateur) ou un JWT (API).


Émettre et rafraîchir des JWT

Un JWT (JSON Web Token) est un jeton signé qu'un client envoie au lieu de se connecter à chaque fois. JwtLifecycle gère tout le flux : un jeton d'accès à courte durée de vie plus un jeton de rafraîchissement à durée de vie plus longue, avec vérification, rafraîchissement et révocation intégrés.

use rustango::tenancy::jwt_lifecycle::{JwtLifecycle, JwtTokenPair, JwtIssueError};
use serde_json::json;

let jwt = JwtLifecycle::new(secret)
    .with_access_ttl(900)                         // 15 min
    .with_refresh_ttl(7 * 86400);                 // 7 days

Ce sont aussi les valeurs par défaut. JwtLifecycle::new panique quand secret fait moins de 32 octets, car une clé courte permet à n'importe qui de forger des jetons. issue_pair(user_id) émet une paire sans claims personnalisés, issue_access_with un seul jeton d'accès, et verify_refresh vérifie un jeton de rafraîchissement.

Émettre un jeton avec des claims personnalisés (pas de lookup DB à la vérification)

let pair = jwt.issue_pair_with(user_id, json!({
    "roles":  ["admin", "editor"],
    "tenant": "acme",
    "scope":  "read:posts write:posts",
    "email":  "[email protected]",
}).as_object().unwrap().clone())?;

Les « claims » sont les faits clé/valeur que vous intégrez dans le jeton (rôles, tenant, etc.) ; le client les renvoie et vous les lisez sans toucher à la base de données. Les noms de claim réservés (sub, exp, jti, typ) sont utilisés par le framework et ne peuvent pas apparaître dans vos claims personnalisés — essayer renvoie JwtIssueError::ReservedClaim.

Vérifier un jeton

let claims = jwt.verify_access(&access_token).await
    .ok_or(StatusCode::UNAUTHORIZED)?;

let roles: Vec<String> = claims.get_custom("roles").unwrap_or_default();
let tenant: String = claims.get_custom("tenant").unwrap_or_default();

Rafraîchir un jeton (conserve vos claims personnalisés)

let new_pair = jwt.refresh(&refresh_token).await
    .ok_or(StatusCode::UNAUTHORIZED)?;
// new_pair has the same roles + scope + tenant

Le JTI de l'ancien jeton de rafraîchissement (son ID unique) est ajouté à une liste noire pour qu'il ne puisse pas être réutilisé — cela bloque les attaques par rejeu où un ancien jeton volé est renvoyé. Un jeton de rafraîchissement est à usage unique : de deux rafraîchissements d'un même jeton, même simultanés, le second reçoit None.

Rafraîchir avec re-vérification des permissions

// returns Result<Option<JwtTokenPair>, JwtIssueError>:
// Err on a reserved-claim collision, Ok(None) on an invalid/expired refresh.
let new_pair = jwt.refresh_with(&refresh_token, json!({
    "roles": ["viewer"],     // role was demoted since login
    "tenant": "acme",
}).as_object().unwrap().clone()).await?
    .ok_or(StatusCode::UNAUTHORIZED)?;

Révoquer un jeton

jwt.revoke(&access_token).await;     // adds JTI to blacklist; false if the token isn't ours
jwt.revoke(&refresh_token).await;

La liste noire en mémoire par défaut (InMemoryJtiStore) nettoie d'elle-même les entrées expirées, mais elle vit dans un seul processus et oublie chaque révocation au redémarrage. Pour les déploiements multi-processus, installez un store partagé et durable via JwtLifecycle::new(secret).with_jti_store(store) — store est n'importe quel Arc<dyn JtiStore>. Seul InMemoryJtiStore est fourni, vous écrivez donc vous-même celui adossé à Redis ou à une base. Sans store partagé, un jeton que vous révoquez sur une réplique peut encore être rejoué sur une autre jusqu'à son expiration. Depuis v0.52, tous ces appels sont async — verify_*, refresh* et revoke attendent le store, de sorte qu'un store durable peut être une simple écriture conditionnelle au lieu d'un cache à cohérence à terme doté d'un vidage en arrière-plan.

À approfondir : API d'authentification JWT — le routeur intégré /api/auth/login|refresh|logout|me, le rafraîchissement glissant, et le store de révocation JTI. Pour un seul jeton auto-géré, voir JWT (autonome). Pour restreindre les routes navigateur/API selon la connexion, voir décorateurs d'accès.


S'authentifier avec des clés d'API

Les clés d'API permettent aux scripts et aux services de s'authentifier sans nom d'utilisateur, mot de passe ni session — pratique pour l'accès machine à machine. Vous générez une clé, la montrez à l'utilisateur une seule fois, et ne stockez que son préfixe et son hachage.

use rustango::api_keys::{generate_key_async, verify_key_async, split_token};

// Issuance
let (full_token, prefix, hash) = generate_key_async().await?;
// Format: {8-char hex prefix}.{32-char hex secret}
// Show full_token to the user once. Store prefix + hash in your DB.

// Verification on each request
let (prefix, secret) = split_token(&inbound_header)
    .ok_or(StatusCode::UNAUTHORIZED)?;
let row = lookup_by_prefix(prefix).await?;
if !verify_key_async(secret, &row.hash).await? {
    return Err(StatusCode::UNAUTHORIZED);
}

Ces clés fonctionnent directement avec le ApiKeyBackend de la multi-tenancy — les deux utilisent le même format {prefix}.{secret}. Le backend stocke un HMAC-SHA256 du secret (hmac-sha256v2$…) ; il accepte aussi un hash argon2id issu d'api_keys et le remplace par le HMAC au premier usage, de sorte qu'une clé émise ici s'authentifie là-bas sans travail supplémentaire.


Ajouter l'authentification à deux facteurs (TOTP)

Le TOTP est le code à 6 chiffres d'une application d'authentification — un second facteur en plus du mot de passe. Vous générez un secret par utilisateur, le montrez sous forme de QR code pour l'enrôlement, puis vérifiez le code qu'il saisit à chaque connexion. Il suit la norme RFC 6238.

use rustango::totp::{TotpSecret, otpauth_url, verify};

// Enrollment
let secret = TotpSecret::generate();                           // 20 random bytes
user.totp_secret = secret.to_base32();                          // store in DB
let qr_url = otpauth_url("MyApp", &user.email, &secret);        // encode as QR

// Verification on login
let secret = TotpSecret::from_base32(&user.totp_secret).unwrap();
if !verify(&secret, &user_supplied_code, 30, 6, 1) {            // 6 digits, ±30s drift
    return Err("bad TOTP code");
}

Fonctionne avec Google Authenticator, Authy, 1Password, Bitwarden et d'autres applications d'authentification standard.

verify accepte le même code à nouveau jusqu'à son expiration. Pour des codes à usage unique, appelez plutôt matched_step, stockez le pas qu'il renvoie et n'acceptez un code que si son pas est postérieur au pas stocké. La connexion admin intégrée fait ainsi.

Avec la fonctionnalité totp, le bare admin a aussi une connexion à deux facteurs. Chaque utilisateur s'enrôle sur <admin>/account/totp, et un appareil confirmé est demandé à chaque connexion, SSO compris. Le désactiver demande un code actuel ; pour un appareil perdu, lancez manage reset-admin-totp <username> (reset-operator-totp pour un opérateur). L'inscription, la désactivation et les codes faux écrivent des lignes d'audit.

La console opérateur a le même second facteur, facultatif par opérateur ou obligatoire pour tous ; voir Connexion à deux facteurs.

Codes de récupération (codes de secours à usage unique pour quand un utilisateur perd son téléphone) pas encore fournis. Le motif courant est de stocker 8 à 10 codes hachés par utilisateur et d'en brûler un à chaque utilisation.


Envoyer des URL signées (liens magiques)

Une URL signée porte une signature infalsifiable, de sorte que vous pouvez lui faire confiance sans session — parfait pour les connexions par lien magique, les réinitialisations de mot de passe et les liens de téléchargement à durée limitée. Vous sign une URL (optionnellement avec une expiration) et la verify quand l'utilisateur clique.

use rustango::signed_url::{sign, verify, SignedUrlError};
use std::time::Duration;

// Issue a 1-hour magic-link login URL
let url = sign(
    "https://app.example.com/auth/[email protected]",
    secret,
    Some(Duration::from_secs(3600)),
);
// Send via email...

// On the callback handler
match verify(&incoming_url, secret) {
    Ok(()) => { /* identity confirmed */ }
    Err(SignedUrlError::Expired) => { /* prompt to request a new link */ }
    Err(SignedUrlError::InvalidSignature) => { /* tampered — log + 401 */ }
    Err(_) => { /* malformed */ }
}

Usages courants :

  • Connexion par lien magique (envoyer par email une URL à usage unique au lieu de demander un mot de passe)
  • Confirmation de réinitialisation de mot de passe
  • Téléchargements de fichiers à durée limitée
  • Liens « Cliquez ici pour vérifier votre email »
  • Liens de désinscription (aucune authentification nécessaire ; l'URL elle-même prouve l'intention)

La signature est un HMAC-SHA256 sur le schéma, l'hôte, le chemin et la query, triée d'abord pour que l'ordre des paramètres ne compte pas. En changer un élément, expires compris, la casse.

Ces liens ne sont pas à usage unique. verify ne vérifie que la signature et l'expiration, donc un lien qui fuit (un en-tête Referer, l'historique du navigateur, un e-mail transféré) fonctionne jusqu'à son expiration. Pour un lien qui connecte quelqu'un ou modifie des données, utilisez les variantes verify_single_use de auth_flows, ou supprimez l'enregistrement après le premier clic.

À approfondir : Flux de compte construit la réinitialisation de mot de passe, la vérification d'email et la connexion par lien magique sur cette primitive d'URL signée.


Vérifier les webhooks entrants

Un webhook est un rappel HTTP qu'un autre service vous envoie (un paiement a réussi, un push a eu lieu). Vérifiez toujours sa signature pour savoir qu'il provient réellement de ce service et que le corps n'a pas été modifié. verify_signature gère les formats courants.

Stripe et Slack ne signent pas le corps seul : ils signent un horodatage joint au corps, et c'est cet horodatage qui empêche un rejeu. Construisez cette chaîne vous-même et vérifiez l'horodatage, comme ci-dessous. Stripe signe "{t}.{body}" avec tout votre secret whsec_… comme clé ; Slack signe "v0:{ts}:{body}" et envoie v0=<hex>.

use axum::{body::Bytes, http::HeaderMap, http::StatusCode};
use rustango::webhook::{verify_signature, SignatureFormat};

/// Stripe sends `Stripe-Signature: t=<unix>,v1=<hex>[,v1=<hex>]`
/// and signs `"{t}.{body}"`, not the body alone.
fn verify_stripe(secret: &[u8], header: &str, body: &[u8], now: i64, tolerance: i64) -> bool {
    let mut ts = None;
    let mut sigs = Vec::new();
    for part in header.split(',') {
        match part.split_once('=') {
            Some(("t", t)) => ts = Some(t),
            Some(("v1", sig)) => sigs.push(sig),
            _ => {}
        }
    }
    let Some(ts) = ts else { return false };
    let Ok(t) = ts.parse::<i64>() else {
        return false;
    };
    if (now - t).abs() > tolerance {
        return false; // stale or future-dated: a replay
    }
    let mut signed = format!("{ts}.").into_bytes();
    signed.extend_from_slice(body);
    sigs.iter()
        .any(|sig| verify_signature(SignatureFormat::HexSha256, secret, &signed, sig))
}

async fn handle_stripe_webhook(headers: HeaderMap, body: Bytes) -> StatusCode {
    let Ok(secret) = std::env::var("STRIPE_WEBHOOK_SECRET") else {
        return StatusCode::INTERNAL_SERVER_ERROR;
    };
    let header = headers
        .get("stripe-signature")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");
    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |d| d.as_secs() as i64);
    if !verify_stripe(secret.as_bytes(), header, &body, now, 300) {
        return StatusCode::UNAUTHORIZED;
    }
    // ... process the verified payload
    StatusCode::OK
}
FormatSigneUtilisé par
HexSha256WithPrefixcorps, sha256=<hex>GitHub (X-Hub-Signature-256)
HexSha256les octets passés, hex brutvaleurs v1= de Stripe / v0= de Slack sur les chaînes ci-dessus
Base64Sha256corps, base64 standardShopify (X-Shopify-Hmac-Sha256)

Webhooks issus de webhook_delivery

Les livraisons propres à Rustango portent X-Webhook-Signature-V2, signé sur l'id, l'événement, l'horodatage et le corps. Vérifiez-le avec verify_delivery, puis écartez un X-Webhook-Id déjà vu pendant max_age. Choisissez un max_age plus long que la durée possible d'attente des tâches en file.

use axum::{body::Bytes, http::HeaderMap, http::StatusCode};
use rustango::webhook::{verify_delivery, DeliveryHeaders, SignatureFormat};

fn check(secret: &[u8], headers: &HeaderMap, body: &Bytes) -> StatusCode {
    let h = |name| headers.get(name).and_then(|v| v.to_str().ok()).unwrap_or("");
    let signed = DeliveryHeaders::new(
        h("x-webhook-id"),
        h("x-webhook-event"),
        h("x-webhook-timestamp"),
        h("x-webhook-signature-v2"),
    );
    let max_age = std::time::Duration::from_secs(600);
    if !verify_delivery(SignatureFormat::HexSha256WithPrefix, secret, &signed, body, max_age) {
        return StatusCode::UNAUTHORIZED;
    }
    // ... drop a repeated id, then process
    StatusCode::OK
}

L'ancien X-Webhook-Signature ne couvre que le corps et est encore envoyé pendant que les destinataires passent à la v2.

Une livraison qui reçoit 408, 429 ou 5xx, ou qui échoue au niveau du transport, est retentée : 8 exécutions au total, avec une attente de 1s qui double à chaque fois. WebhookSubscription::max_attempts(n) et retry_backoff(base) changent les deux pour un abonnement. Un Retry-After sur une 429 ou une 503, en secondes ou en date HTTP, fait attendre la tentative suivante au moins aussi longtemps, mais jamais au-delà de deux minutes après l'envoi, pour que l'horodatage signé reste frais. Les autres réponses 4xx partent en dead-letter tout de suite ; retry_status_codes([...]) ajoute des codes à retenter. Les tentatives réutilisent le premier horodatage, donc le max_age du receveur doit couvrir toute la fenêtre de tentatives.

La comparaison de signature est à temps constant, ce qui signifie qu'elle prend toujours le même temps que la supposition soit correcte ou fausse. Cela stoppe les attaques temporelles, où un attaquant mesure de minuscules différences de temps de réponse pour deviner le secret un caractère à la fois.

Les appels sortants vers des URL que la configuration peut définir (livraison de webhooks, webhook_callback de Slack, découverte OAuth2/OIDC, token et userinfo) refusent les adresses de loopback, privées, link-local et de métadonnées, et ne suivent jamais les redirections. Pour joindre un IdP ou un hook Slack sur votre propre réseau, listez-le dans RUSTANGO_OUTBOUND_ALLOW (hôtes et CIDR séparés par des virgules, p. ex. 10.0.5.0/24,idp.internal) ; tout le reste reste refusé. Une entrée d'hôte fait confiance à tout ce vers quoi ce nom résout : ne listez que des noms que vous contrôlez. La liste ne s'applique jamais à la livraison de webhooks : un abonnement s'y inscrit avec allow_private_targets(true). Elle ne s'applique pas non plus aux fournisseurs SSO propres à un tenant, qu'un admin du tenant définit : ceux-ci lisent RUSTANGO_TENANT_OUTBOUND_ALLOW (vide par défaut, donc adresses publiques seulement).

Ces appels ignorent HTTPS_PROXY/NO_PROXY. Pour les faire passer par un proxy de sortie, définissez RUSTANGO_OUTBOUND_PROXY (p. ex. http://proxy.internal:3128) ; le proxy lui-même peut être privé. L'application résout et vérifie quand même chaque cible d'abord : elle a donc besoin d'un DNS local pour elles ; un échec de résolution refuse l'appel. Le proxy résout le nom à nouveau, il doit donc lui aussi refuser les destinations privées et de métadonnées : 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16 (dont 169.254.169.254, 169.254.170.2, 169.254.170.23), 100.64.0.0/10 (dont 100.100.100.200), ::1, fc00::/7 (dont fd00:ec2::254, fd00:ec2::23) et fe80::/10. Sans proxy, les adresses sont vérifiées à nouveau au moment de la connexion.


Garder les secrets hors de vos journaux

Les URL journalisées peuvent divulguer des mots de passe et des jetons qui apparaissent dans les query strings. AccessLogLayer masque automatiquement les paramètres d'identifiant connus avant d'écrire la ligne de journal (PII = informations personnellement identifiables).

let app = router.access_log(AccessLogLayer::default());

Par défaut, un query param est remplacé par [redacted] quand son nom contient un mot secret, comparé mot à mot, donc api_key, reset_token et X-Api-Key comptent tous. Les mots incluent password, pass, pwd, token, jwt, secret, key, signature, auth, credential, cookie, session et otp, plus les noms OAuth code, state et assertion.

Ajouter à la liste :

let layer = AccessLogLayer::default()
    .redact_additional("session_id")
    .redact_additional("private_key");

Remplacer toute la liste :

let layer = AccessLogLayer::default()
    .redact(vec!["only_this".into()]);

token, signature et code restent masqués même après .redact(...), car le framework y place des identifiants.

Note : ceci masque uniquement les query strings. Pour nettoyer les corps de requête ou les en-têtes, filtrez à la source avec tracing::Subscriber.


Tracer les requêtes entre services

Un identifiant de requête étiquette chaque ligne de journal d'une même requête avec le même ID, de sorte que vous pouvez suivre cette requête à travers les handlers — et à travers les services. RequestIdLayer en ajoute un à chaque requête.

let app = router.request_id(RequestIdLayer::default());

Il ne réutilise un X-Request-Id entrant que s'il vient d'un proxy nommé dans RealIpLayer::trust_proxies (ou Cli::with_trusted_proxies), pour que les services chaînés partagent un seul ID, et génère sinon un nouvel ID base64 de 22 caractères. Les IDs entrants doivent compter au plus 128 caractères ASCII visibles, sans guillemet ni barre oblique inverse, ce qui bloque l'injection d'en-tête et de journal.

Dans les handlers :

async fn handler(id: rustango::request_id::RequestId) -> String {
    tracing::info!(req_id = %id.0, "handling /me");
    format!("req {}", id.0)
}

Pour mettre l'ID sur chaque ligne de journal de la requête, montez aussi tracing_layer::TracingLayer::new() : son span de requête a un champ request_id que la couche remplit. Sans lui, l'ID n'arrive que dans l'en-tête de réponse.

Dans une configuration zero-trust, où vous ne faites pas confiance aux IDs envoyés par les services en amont, générez toujours le vôtre :

router.request_id(RequestIdLayer::always_generate());

Gérer les secrets

Ne codez jamais en dur des secrets (mots de passe de base de données, clés d'API) dans votre source.

Vos fichiers config/*.toml sont commités dans git, donc n'y mettez pas non plus de mots de passe. Tout réglage peut venir d'une variable d'environnement nommée RUSTANGO__SECTION__KEY. Par exemple, RUSTANGO__MAIL__SMTP_PASSWORD définit [mail] smtp_password. Sur votre machine, mettez-la dans .env (le .gitignore généré laisse .env hors de git) ; en production, dans les réglages de secrets de votre hébergeur. Voir Garder le mot de passe SMTP hors de git.

Les secrets dont votre propre code a besoin, lisez-les à l'exécution via le trait Secrets, qui abstrait l'endroit où ils vivent réellement. (Un « trait » est la version Rust d'une interface.) Le EnvSecrets intégré lit depuis les variables d'environnement.

use rustango::secrets::{Secrets, EnvSecrets, BoxedSecrets};
use std::sync::Arc;

// Env vars (with optional prefix)
let secrets: BoxedSecrets = Arc::new(EnvSecrets::with_prefix("MYAPP_"));

let db_pwd = secrets.require("DB_PASSWORD").await?;       // reads MYAPP_DB_PASSWORD
let redis_url = secrets.get("REDIS_URL").await?;          // None when unset

Pour extraire des secrets depuis Vault, AWS Secrets Manager ou GCP Secret Manager, implémentez le trait vous-même — ce n'est qu'une seule méthode async, get. En test, utilisez InMemorySecrets::new().with(&[("DB_PASSWORD", "x")]).


Auditer avant de déployer

Avant de passer en production, lancez l'audit intégré. Il attrape les mauvaises configurations courantes — comme un secret de signature manquant ou trop court — que vous ne voulez pas découvrir en production.

manage check --deploy

Vérifications toujours actives (exécutées avec ou sans --deploy) :

  • ✅ Modèles enregistrés dans l'inventaire
  • ✅ DB joignable (SELECT 1)
  • ✅ Migrations sur disque pour les modèles enregistrés

Vérifications --deploy supplémentaires (durcissement pour la production) :

  • ✅ RUSTANGO_ENV est prod ou production
  • ✅ RUSTANGO_SESSION_SECRET défini et décodant en ≥ 32 octets (la clé HMAC pour la signature des cookies + JWT — SECRET_KEY n'est pas lu par le framework), sans placeholder du scaffolder laissé en place. C'est du base64 : openssl rand -base64 32 produit 44 caractères. Un secret de 32 caractères ne fait que 24 octets et est refusé — par check --deploy comme par le runtime ; c'est précisément l'objectif, car la vérification mesurait auparavant la chaîne encodée et laissait passer une valeur que l'application rejetait ensuite
  • ✅ Une base de données est configurée : DATABASE_URL, ou DB_USER + DB_NAME (et avertit si elle pointe vers localhost)
  • ⚠️ Avertissements de cohérence RUSTANGO_APEX_DOMAIN / RUSTANGO_BIND pour la tenancy + le binding non-loopback
  • ⚠️ Des réglages laissés aux valeurs de dev dans le tier prod : [security] headers_preset, secure_cookies = false, hsts_max_age_secs = 0, allowed_hosts vide ou "*", "*" dans cors_allowed_origins, csrf_trusted_origins vide, pas de secure_ssl_redirect ; [server] request_timeout_secs et max_body_bytes non définis ; un [auth] argon2_memory_kib bas ; un [auth.jwt] access_ttl_secs au-delà d'une heure ; [mail] backend non défini ou console
  • ⚠️ Un routeur admin sans authentification, un store de verrouillage des connexions local au processus, la collation et le fuseau horaire de la base, des modèles dont la base n'a pas le required_db_vendor ou les required_db_features, et des providers SSO qui refuseraient tout utilisateur

RUSTANGO_SECRET_KEY est une autre clé : elle chiffre les secrets stockés comme les secrets client SSO. Quand le provisionnement des tenants est monté, check --deploy avertit si elle manque ou fait moins de 32 octets.

Renvoie un code de sortie non nul en cas de constat de niveau erreur (idéal pour les gates de CI). Les avertissements ne déclenchent pas d'échec mais s'affichent dans la sortie.

Pour des vérifications au-delà de ce qui est fourni, enregistrez votre propre verbe avec register_command! et lancez-le à côté de check --deploy.


Ce qui n'est PAS encore fourni

Quelques flux de bout en bout ont encore besoin d'être assemblés à partir des primitives ci-dessous :

  • Réinitialisation de mot de passe + vérification d'email — les helpers d'émission/vérification de jeton existent (auth_flows::confirm_password_reset_pool, plus les allers-retours de vérification d'email) et le pipeline d'email est fourni séparément, mais il n'y a pas de cycle unique préconstruit vue + email + validation câblé pour vous.
  • Masquage PII du corps de requête / des en-têtes dans access_log — le masquage de journal au niveau des champs existe (voir Garder les secrets hors de vos journaux), mais pas le nettoyage automatique du corps de requête ou des en-têtes.

Déjà fournis (n'allez pas chercher un contournement) :

  • Connexion sociale OAuth2 / OIDC — oauth2::providers fournit les helpers Google, GitHub, Microsoft, GitLab et Discord (plus OAuth2Provider::from_discovery pour tout fournisseur OIDC), et oauth2::router::oauth2_router monte les routes de login + callback ; votre hook OnAuthSuccess retrouve l'utilisateur via AuthSuccess::identity_key() et définit le cookie de session.
  • Verrouillage par compte — rustango::account_lockout::Lockout (adossé au cache ; is_locked / record_failure / clear, max_attempts + lockout_duration configurables).
  • Endpoint de rapport CSP — security_headers::csp_report_router(path) + SecurityHeadersLayer::csp_report_uri(uri).
  • Limitation de débit distribuée — rate_limit_cache::CacheRateLimitLayer (voir Limiter le débit des requêtes).

Jusqu'à ce que les flux non fournis arrivent, assemblez-les à partir des primitives ci-dessus (signed_url::sign pour les jetons de réinitialisation de mot de passe, le pipeline d'email pour la livraison, etc.).


Voir aussi

  • Middleware — comment les couches de sécurité s'attachent, leur ordre, et le catalogue complet.
  • Authentification — mots de passe, sessions, JWT, clés d'API, HMAC, backends d'authentification et flux de compte, chacun en profondeur.
  • Conventions d'API — les règles de type d'erreur et de type de retour derrière ces API.