Rustango docs
← Autenticación

Decoradores de acceso

Una vez que un usuario está autenticado, restringes rutas. Rustango entrega para ello una familia de capas de axum componibles: adjunta una a un router y las peticiones anónimas son rechazadas — redirigidas con 302 a tu página de inicio de sesión (flujo de navegador) o respondidas con 401/403 (flujo de API) — antes de que lleguen siquiera al handler.

Decoradores de acceso: login_required redirige con 302 a los navegadores anónimos a /login?next=, la familia _or_403 devuelve 401/403 para APIs, superuser_required restringe por rol

Fuente: rustango::auth_decorators (login_required, login_required_or_401, user_passes_test, superuser_required, active_required, permission_required + las variantes _or_403; safe_next, extract_next) — las barreras están detrás de la característica tenancy y solo funcionan bajo el servidor de tenancy (leen el extractor SessionUser). safe_next, extract_next, extract_next_named y redirect_to_login solo necesitan axum.

Versión ejecutable: el comportamiento de restricción está cubierto por el auth_demo probado — cargo test -p auth_demo --test auth_decorators.

¿Algún término aquí es nuevo para ti? middleware/capa, extractor, 401/403 — consulta el glosario.

Compañero de inmersión profunda de la guía de seguridad.

Solo para apps con tenancy. Las barreras leen una sola cosa: la cookie firmada rustango_tenant_session, a través del extractor SessionUser. El servidor de tenancy pone esa cookie cuando un usuario inicia sesión en el login del inquilino (/login por defecto), por SSO, o cuando un operador suplanta a un usuario. El extractor también necesita el contexto de inquilino que monta el servidor de tenancy. Las barreras no leen sesiones de SessionStore. En una app de una sola base de datos, o en un router sin el servidor de tenancy, toda petición cuenta como anónima: login_required redirige a la página de login cada vez. Consulta Aplicaciones de una sola base de datos para saber qué usar ahí.


Tabla de contenidos


Inicio rápido

use rustango::auth_decorators::login_required;

// Scope the gate to a sub-router (the idiomatic shape):
let private = Router::new()
    .route("/profile", get(profile))
    .route("/settings", get(settings))
    .layer(login_required("/login"));      // anonymous → 302 /login?next=...

let app = Router::new()
    .route("/", get(home))                 // public
    .merge(private);

Las peticiones anónimas a /profile se redirigen a /login?next=%2Fprofile; una petición autenticada pasa hasta el handler.


Barreras de navegador vs. API

La misma barrera viene en dos formas de respuesta. Elige según lo que el llamante puede hacer con la respuesta:

  • Navegador / HTML → las barreras base redirigen con 302 a tu página de inicio de sesión (un humano puede seguirla e iniciar sesión).
  • API JSON → la familia _or_403 devuelve códigos de estado: 401 Unauthorized para anónimo, 403 Forbidden para autenticado-pero-no-permitido (un cliente no puede renderizar una página de inicio de sesión HTML, y la división 401/403 le permite distinguir «inicia sesión» de «no puedes hacer eso»).
// Browser: redirect to /login
let app = Router::new().route("/dashboard", get(dash)).layer(login_required("/login"));

// API: 401 for anonymous, never a redirect
let api = Router::new().route("/api/me", get(me)).layer(login_required_or_401());

La familia de barreras

Barrera (navegador, 302)Variante de API (401/403)Deja pasar
login_required(url)login_required_or_401()cualquier usuario con sesión iniciada
active_required(url)active_required_or_403()con sesión iniciada y active
superuser_required(url)superuser_required_or_403()is_superuser && active
user_passes_test(url, pred)user_passes_test_or_403(pred)predicado sobre la fila User
permission_required(url, codename) †permission_required_or_403(codename)posee el codename de permiso
† permission_required es la única barrera de esta columna que no siempre redirige. Un visitante anónimo recibe el 302 a login_url; quien sí ha iniciado sesión pero carece del codename recibe un 403 pelado, sin redirección ni cuerpo. Las otras cuatro redirigen en todos los casos de fallo.

Todas son capas tower — .layer(...)-las sobre un router o subrouter.


Barreras por predicado y por rol

user_passes_test ejecuta tu closure contra la fila User resuelta, de modo que puedes restringir por cualquier campo:

use rustango::auth_decorators::{user_passes_test, superuser_required_or_403};

// Staff-only sub-router (browser):
let staff = Router::new()
    .route("/admin/dashboard", get(dashboard))
    .layer(user_passes_test("/login", |u| u.is_superuser));

// Superuser-only JSON API → 401 anonymous / 403 non-superuser:
let api = Router::new()
    .route("/api/admin/stats", get(stats))
    .layer(superuser_required_or_403());

superuser_required / active_required son atajos fijados para los predicados comunes is_superuser && active / active, de modo que los puntos de llamada no divergen silenciosamente en si las cuentas desactivadas siguen contando.


Barreras de permiso

permission_required comprueba un codename de permiso contra el motor de permisos del inquilino (los superusuarios lo eluden automáticamente). Además resuelve el extractor Tenant, así que las rutas que lo usan deben montarse bajo el contexto del inquilino:

use rustango::auth_decorators::permission_required;
use rustango::tenancy::permissions::ACCESS_ADMIN_CODENAME;

let admin = Router::new()
    .route("/admin", get(dashboard))
    .layer(permission_required("/login", ACCESS_ADMIN_CODENAME));

El viaje de ida y vuelta de ?next=

login_required conserva la URL solicitada originalmente en ?next= para que tu handler de inicio de sesión pueda devolver al usuario tras autenticarse. Debes sanear ese valor — reflejarlo en una redirección sin comprobarlo es un agujero de redirección abierta (phishing) de manual. safe_next es la salvaguarda:

use rustango::auth_decorators::{extract_next, safe_next};

async fn login_post(Query(q): Query<HashMap<String, String>>, /* … */) -> Response {
    // … verify credentials, set the session …
    let dest = extract_next(&q)
        .and_then(|n| safe_next(&n))          // rejects open redirects
        .unwrap_or_else(|| "/".to_owned());
    Redirect::to(&dest).into_response()
}

safe_next solo acepta rutas del mismo origen, relativas a la raíz — rechaza las URL absolutas, las //host relativas al esquema, las variantes con barra invertida, sus formas codificadas en porcentaje, los caracteres de control y los valores vacíos:

assert_eq!(safe_next("/dashboard"),            Some("/dashboard".to_owned()));
assert_eq!(safe_next("https://evil.example/x"), None);
assert_eq!(safe_next("//evil.example/x"),       None);   // scheme-relative
assert_eq!(safe_next("%2F%2Fevil.example/x"),   None);   // decodes to //evil

Aplicaciones de una sola base de datos

Hoy no hay una barrera lista para una app sin tenancy. Usa una de estas opciones:

  • Páginas de staff en el admin. El admin simple tiene su propio login. Llama a with_session_auth(secret) en rustango::admin::Builder y cada ruta del admin pide un usuario admin con sesión iniciada. El admin pone la sesión en la petición como Extension<AdminSession>. Esta barrera cubre solo el router del admin, no tus propias rutas.
  • Tus propias rutas. Escribe un middleware pequeño con axum::middleware::from_fn: lee tu cookie de sesión, carga la sesión con SessionStore::load y, si no hay usuario en ella, devuelve redirect_to_login(login_url, "next", original_path). En el handler de login, lee ?next= con extract_next y pásalo por safe_next, como se muestra arriba. Estos helpers no necesitan la característica tenancy. Para una API con tokens en lugar de cookies, Primeros pasos, Paso 14 lo construye completo: un modelo de usuario, handlers de registro e inicio de sesión y un middleware de token Bearer.

Notas y límites

  • «Con sesión iniciada» significa una sesión de inquilino. El extractor SessionUser resolvió un usuario activo a partir de la cookie rustango_tenant_session de este inquilino. Una cookie de otro inquilino, una caducada, o una emitida antes del último cambio de contraseña o cierre de sesión cuenta como anónima. La autenticación por token de API (JWT, claves de API) se restringe en su lugar en la capa de la cadena de backends, leyendo la cabecera Authorization.
  • El orden de las capas importa. .layer(gate) protege cada ruta añadida al router antes de ella; las rutas añadidas después son públicas. Acotar la barrera a un subrouter dedicado (la forma del inicio rápido) evita esa trampa.
  • permission_required necesita contexto de inquilino (consulta el motor de permisos del inquilino) — móntalo bajo el inquilino; una ruta sin inquilino provoca un 500.
  • El ?next= de la redirección siempre está codificado en porcentaje, de modo que CRLF / división de respuestas no puede filtrarse en la cabecera Location.
  • ¿Escribes tu propia barrera? redirect_to_login(login_url, "next", original) construye el mismo 302, y extract_next_named(&q, field) lee un campo distinto de next.

Véase también