Rustango docs
← Autenticación

Flujos de cuenta (restablecimiento, verificación, enlace mágico)

Los flujos que toda aplicación necesita en los márgenes del inicio de sesión: restablecimiento de contraseña, verificación de correo electrónico e inicio de sesión por enlace mágico (sin contraseña). Los tres tienen la misma forma — enviar por correo al usuario un enlace a prueba de manipulaciones y con tiempo limitado, y luego actuar cuando hace clic en él — y Rustango los construye sobre un mismo sustrato: las URL firmadas. Una URL firmada es una URL normal con una firma HMAC añadida, de modo que el servidor puede confiar en sus parámetros sin almacenar nada.

Flujos de cuenta en Rustango: signed_url::sign añade una firma HMAC + caducidad; los tres flujos (restablecimiento de contraseña, verificación de correo, enlace mágico) emiten un enlace, lo envían por correo y lo verifican al hacer clic

¿Algún término aquí es nuevo para ti? HMAC, token, caducidad — consulta el glosario.

Fuente: rustango::signed_url (sign, verify, SignedUrlError) y rustango::auth_flows (PasswordReset, EmailVerification, MagicLink, confirm_password_reset_pool_into) — tras las funcionalidades signed_url / auth_flows (activadas por defecto; la confirmación de restablecimiento también necesita passwords + un backend de BD).

Versión ejecutable: cada fragmento está copiado de auth_flows_doc.rs (cargo test -p rustango --features sqlite --test auth_flows_doc).

Tabla de contenidos


URL firmadas: el sustrato

sign añade una firma HMAC-SHA256 (y una caducidad opcional) sobre toda la URL antes del fragmento: esquema, host, ruta y query. Verifica la URL pública completa, no req.uri() (sin esquema ni host). verify la vuelve a calcular: manipula cualquier parámetro, usa el secreto equivocado o deja que caduque, y falla.

use rustango::signed_url::{sign, verify, SignedUrlError};

let url = "https://app.example.com/files/42?user_id=7";
let signed = sign(url, secret, None);     // None = never expires
assert!(verify(&signed, secret).is_ok());

// Flip any signed byte → InvalidSignature.
let tampered = signed.replace("user_id=7", "user_id=8");
assert_eq!(verify(&tampered, secret), Err(SignedUrlError::InvalidSignature));

Añade un TTL y un enlace caducado se rechaza (sign_at / verify_at toman segundos unix explícitos para pruebas deterministas):

use rustango::signed_url::{sign_at, verify_at, SignedUrlError};

let signed = sign_at(url, secret, Some(100));         // expires at t=100
assert!(verify_at(&signed, secret, 50).is_ok());      // before → ok
assert_eq!(verify_at(&signed, secret, 1000), Err(SignedUrlError::Expired));

La query se ordena antes de firmar, así que el orden de los parámetros no importa. Los errores son MissingSignature, MalformedSignature, InvalidSignature, Expired.


Restablecimiento de contraseña

Los asistentes de auth_flows envuelven las URL firmadas con una etiqueta de propósito (para que un token de restablecimiento no pueda reproducirse como un enlace mágico) y codifican el identificador del usuario. PasswordReset también incluye un asistente de confirmación que verifica el token y rota el hash almacenado en una sola llamada.

use std::time::Duration;
use rustango::auth_flows::{LinkScope, PasswordReset, confirm_password_reset_pool};

// The request's tenant (`t: Tenant`): links redeem only in it.
let scope = LinkScope::from(&t);

// 1. User asks to reset → look them up → issue a link → email it.
let url = PasswordReset::issue(
    &scope,
    "https://app.example.com/auth/reset",   // your callback route
    user_id,                                // encoded in the token
    secret,
    Duration::from_secs(3600),              // 1-hour TTL
);
mailer.send(&Email::new().to(addr).subject("Reset your password").body(&url)).await?;

// 2. User clicks + submits a new password → verify + rotate the hash.
let user_id = confirm_password_reset_pool(
    &t, &url, "a-brand-new-strong-password", secret,
).await?;

Las apps multi-tenant deben pasar &t (el Tenant, o un TenantScope) a la confirmación, para que el pool y el ámbito salgan del mismo valor. Un enlace emitido para otro ámbito falla con Err(WrongScope). LinkTarget::audience(SingleDb::new(&pool), "app") y LinkScope::audience(SingleDb::new(&pool), "app") son para apps con una sola base de datos de usuarios.

Usa esta forma para rustango_users. Las sesiones del framework llevan una huella del hash de la contraseña, así que el nuevo hash termina toda sesión emitida antes del restablecimiento, incluida la de un atacante. También marca password_changed_at, que registra el cambio pero no es lo que termina las sesiones.

El asistente de confirmación aplica la política de contraseñas, aplica argon2id al nuevo password y lo escribe — rechazando entradas débiles, caducadas, manipuladas o con el secreto equivocado sin tocar la fila:

// valid token + strong pw → hash rotated (starts "$argon2…")
// "12345678"               → Err(WeakPassword), nothing written
// user_id tampered         → Err(InvalidSignature), nothing written

Es el mismo passwords::strength_score que usa el resto del framework, así que una contraseña rechazada en el registro no puede establecerse restableciéndola.

_into apunta a tu propia tabla/columnas — un app_users del inquilino, por ejemplo. Solo escribe el hash. Las sesiones que emite el framework terminan con ese nuevo hash; una comprobación de sesión que escriba tu app debe comparar también el hash, o marcar su propia columna en la misma transacción.

Haz que el enlace sea de un solo uso

confirm_password_reset_pool solo escribe mientras password_changed_at sea anterior al enlace, y actualiza esa columna. Así que cualquier cambio de contraseña, este incluido, invalida todos los enlaces anteriores: una repetición recibe Err(Expired).

La forma _into no tiene esa columna, así que su enlace sigue siendo utilizable durante todo su TTL — incluso después de cambiar la contraseña. Una copia del correo en un buzón compartido, un mensaje reenviado o un ticket de soporte con el correo pegado es una toma de control de la cuenta en funcionamiento hasta que el token caduque, en un momento en que el usuario legítimo ya ha terminado y no tiene motivo para sospechar. Dos clics simultáneos también pueden pasar ambos la comprobación de fecha.

Pasa una caché y el token se consume en el primer uso:

use rustango::auth_flows::confirm_password_reset_single_use;

let user_id = confirm_password_reset_single_use(
    &t, &url, "a-brand-new-strong-password", secret, &cache,
).await?;                      // una repetición → Err(AuthFlowError::AlreadyUsed)

_single_use_into toma la misma tabla/columnas que _into. La política de contraseñas se comprueba antes de consumir el token, de modo que una contraseña rechazada no le cuesta el enlace al usuario.

La marca de usado vive en la caché, no en el token, así que todas las réplicas deben compartir una caché — dos instancias significan dos listas negras y ninguna aplicación.


Verificación de correo electrónico

EmailVerification codifica tanto el identificador del usuario como el correo electrónico, de modo que al verificar recuperas ambos y puedes confirmar que la dirección sigue coincidiendo (atrapando enlaces enviados antes de un cambio de correo). Aquí no hay ninguna escritura en BD integrada — tú defines tu propia columna «verificado»:

use rustango::auth_flows::EmailVerification;

// On signup:
let url = EmailVerification::issue(&scope, callback, user_id, &email, secret, Duration::from_secs(86_400));
mailer.send(&Email::new().to(&email).subject("Confirm your email").body(&url)).await?;

// On click:
let (user_id, email) = EmailVerification::verify(&scope, &url, secret)?;
// → if email still matches the user's current address, mark them verified

Inicio de sesión por enlace mágico

MagicLink codifica solo el correo electrónico — el usuario hace clic, tú buscas la cuenta y acuñas una sesión. Mantén el TTL corto (10–30 min) y hazlo de un solo uso (siguiente sección), ya que el enlace es la credencial:

use rustango::auth_flows::MagicLink;

let url = MagicLink::issue(&scope, callback, &email, secret, Duration::from_secs(900));
mailer.send(&Email::new().to(&email).subject("Your sign-in link").body(&url)).await?;

// On click:
let email = MagicLink::verify_single_use(&scope, &url, secret, &cache).await?;
// → look up the user by email, create a session

Tokens de un solo uso

verify por sí solo únicamente comprueba firma + caducidad, así que un enlace filtrado es reproducible hasta que caduca. Para el inicio de sesión y el restablecimiento, prefiere verify_single_use(scope, url, secret, &cache) — registra la firma del token en un Cache y rechaza un segundo uso. Para el restablecimiento en concreto, confirm_password_reset_single_use lo hace dentro de la misma llamada (arriba):

// first click  → Ok(email)
// same link reused → Err(AuthFlowError::AlreadyUsed)

Respáldalo con un caché compartido (Redis) en producción para que un token no pueda reproducirse contra una réplica distinta. La comprobación falla en modo cerrado (un error de caché o un NullCache rechaza en lugar de arriesgar una reproducción). La comprobación es un Cache::add atómico; un Cache propio debe implementar add de forma atómica, como hacen todos los backends incluidos.


Lo que aportas tú

El framework emite/verifica los tokens y (para el restablecimiento) escribe el hash; tu aplicación aporta el resto:

  • Un secreto (una clave de aplicación estable; 32 bytes por convención).
  • Un mailer para enviar los enlaces — rustango::email incluye ConsoleMailer, FileMailer, NullMailer, InMemoryMailer (útil en pruebas) y, con la feature email-smtp, SmtpMailer.
  • Una tabla de usuarios con las columnas que cada flujo necesita (correo para la búsqueda de verificación/enlace mágico; una columna de hash de contraseña para el restablecimiento; una columna «verificado» que es tuya).
  • Las rutas de callback que reciben el clic y la acuñación de sesión para el inicio de sesión por enlace mágico.

Véase también