pagetop-website/doc/v0.6/es/src/how-to/users.md
Manuel Cillero 4e007feec8 📝 Doc cron, mail queue, CSRF and flash messages
Add the scheduled tasks guide, environment variable overrides, the
[mail] and [cron] references, CSRF protection without tokens, flash
messages after redirects and the username policies of pagetop-user.
Update the framework comparison with Poem and Topcoat.
2026-11-02 14:46:28 +01:00

13 KiB
Raw Blame History

Añadir usuarios y permisos

Objetivo: que los visitantes puedan iniciar sesión y que algunas páginas o acciones sólo estén al alcance de quien tenga el permiso adecuado.

La extensión pagetop-user aporta las cuentas, el inicio de sesión, las sesiones (guardadas en la base de datos), las contraseñas cifradas con Argon2 y el control de acceso por roles, con su interfaz de administración en /admin. Necesita una base de datos: mira antes Conectar una base de datos.

1. Añade la extensión

[dependencies]
pagetop-user   = { git = "https://git.cillero.es/manuelcillero/pagetop" }
pagetop-seaorm = { git = "https://git.cillero.es/manuelcillero/pagetop", features = ["sqlite"] }
# use pagetop::prelude::*;
pub struct Board;

#[async_trait]
impl Extension for Board {
    fn dependencies(&self) -> Vec<ExtensionRef> {
        vec![&pagetop_user::User]
    }
}

User declara por su cuenta lo que necesita: pagetop-seaorm, pagetop-htmx, pagetop-mail y el panel pagetop-admin. Al arrancar crea sus tablas y registra sus rutas, entre ellas /user/login, /user/register, /user (el perfil), /user/email (cambiar el email) y /user/password/reset (recuperar la contraseña).

La recuperación de contraseña envía un correo con un enlace, como el cambio de email, que no se aplica hasta que se confirma desde la nueva dirección. Además, la cuenta recibe un aviso cuando cambia su contraseña o se pide cambiar su dirección. Mientras no configures la sección [mail], los correos se escriben en las trazas en lugar de enviarse; para enviarlos, indica al menos el transporte, el remitente y la URL pública de la aplicación, que forma los enlaces:

# config/production.toml
[mail]
transport = "smtp"
from      = "Garden board <no-reply@example.com>"
base_url  = "https://board.example.com"

[mail.smtp]
host = "smtp.example.com"

2. Configura la base de datos y el primer administrador

# config/common.toml
[database]
db_type = "sqlite"
db_name = "board.db?mode=rwc"
# config/local.toml (not versioned)
[user.seed]
admin_password = "choose-a-long-one"

Con la base de datos vacía, el primer arranque crea la cuenta admin con esa contraseña. Si no la indicas, genera una aleatoria y la muestra una sola vez en el terminal:

pagetop-user: admin account created.
  username: admin
  password: ...

Las demás opciones (registro abierto, bloqueo tras intentos fallidos, límites por IP, duración de las sesiones...) están en la referencia de configuración.

Elige qué nombres de usuario se aceptan

Cada cuenta tiene un nombre de usuario y un email, los dos obligatorios y únicos, y se puede iniciar sesión con cualquiera de ellos. Qué nombres de usuario se admiten lo decide identity_policy:

# config/common.toml
[user]
identity_policy = "unicode"
Valor Caracteres Longitud
"strict" (por defecto) Letras ASCII sin tildes, dígitos, ., _ y - 3 a 32
"unicode" Letras y dígitos de cualquier alfabeto, sin mezclarlos, ., _ y - 3 a 32
"permissive" Los de "unicode", más espacios simples, ' y + 3 a 60

Cada nivel admite todo lo del anterior, y los tres comparten tres reglas:

  • Nunca se admite @, así que un nombre de usuario no puede coincidir con el email de otra cuenta, que también sirve para entrar.
  • No se distinguen mayúsculas: Ana y ana son el mismo usuario. El nombre se muestra tal como se escribió.
  • No se admiten nombres que se confunden a simple vista con otro existente: si existe maria, no se puede crear rnaria, ni сосо (escrito con letras cirílicas) si existe coco. Se comprueba con la tabla de caracteres confusables de Unicode.

Para elegir, piensa en quién crea los nombres más que en dónde se publica la aplicación. Con el registro abierto, cualquiera escoge un nombre que verán los demás y que aparecerá en el saludo de sus correos en cuanto verifique su dirección; si las cuentas sólo las crea un administrador, el riesgo es mucho menor.

Situación Política
Aplicación en Internet con registro abierto "strict"
Comunidad en Internet cuyos usuarios escriben su nombre en su alfabeto "unicode"
Aplicación interna con cuentas creadas por administradores "strict" o "unicode"
Importar cuentas de un sistema con espacios en los nombres (Drupal...) "permissive"

"strict" basta casi siempre: los nombres con tildes o en otros alfabetos tienen su sitio en el nombre visible de la cuenta. Evita "permissive" con el registro abierto, porque los espacios permiten escribir frases («Soporte técnico», «Llama al 900...») que luego se muestran como nombre.

Puedes cambiar de política cuando quieras, y nadie pierde el acceso:

  • A una más abierta, las cuentas existentes no cambian.
  • A una más estricta, los nombres que ya no la cumplen se conservan y sus titulares pueden seguir entrando y guardando su perfil; sólo un nombre nuevo, o uno que se cambia, debe cumplirla. Nada se renombra automáticamente.
  • El administrador inicial ([user.seed] admin_username) se comprueba en cada arranque: si no cumple la política nueva, la aplicación no arranca hasta que pongas uno válido. Cambiarlo no renombra al administrador que ya existe, y con el valor por defecto, admin, no ocurre nunca.

3. Pon el menú de cuenta en la cabecera

account_menu(cx) construye el menú: «Iniciar sesión» para los anónimos, y el nombre del usuario con su perfil, la administración (si tiene acceso) y «Cerrar sesión» para los demás. Depende de quién pide la página, así que se construye al renderizar, dentro de un componente:

# use pagetop::prelude::*;
use pagetop_user::prelude::*;

#[derive(AutoDefault, Clone, Debug)]
struct TopBar;

#[async_trait]
impl Component for TopBar {
    fn new() -> Self {
        Self
    }

    async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
        let brand = Brand::new()
            .with_title(Lc::n("Garden board"))
            .with_route(Route::from("/"));
        Ok(Navbar::brand_left(brand)
            .with_item(navbar::Item::nav(account_menu(cx)))
            .render(cx)
            .await)
    }
}

Regístralo una vez en initialize(), para todas las páginas:

InRegion::Global(&CoreRegions::Header).add(TopBar::new());

4. Define tus permisos

Un permiso es un valor de un enum propio con una clave única. Su nombre y su grupo son los que verá el administrador al asignarlo:

# use pagetop::prelude::*;
#[derive(Clone, Copy, Debug)]
enum BoardPermission {
    PostNotices,
}

impl Permission for BoardPermission {
    fn key(&self) -> CowStr {
        match self {
            Self::PostNotices => "board:post_notices".into(),
        }
    }

    fn label(&self) -> Lc {
        Lc::n("Post notices on the board")
    }

    fn group(&self) -> &'static str {
        "board"
    }

    fn group_label(&self) -> Lc {
        Lc::n("Garden board")
    }
}

Para que aparezca en la pantalla de roles, regístralo con la acción DeclarePermissions:

# use pagetop::prelude::*;
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
#     fn key(&self) -> CowStr { "board:post_notices".into() }
# }
use pagetop_user::PermissionRegistry;
use pagetop_user::prelude::*;

fn declare_permissions(registry: &mut PermissionRegistry) {
    registry.register(&BoardPermission::PostNotices);
}

pub struct Board;

#[async_trait]
impl Extension for Board {
    fn actions(&self) -> Vec<ActionBox> {
        actions![DeclarePermissions::new(declare_permissions)]
    }

    // ... dependencies(), initialize() and configure_router() ...
}

5. Protege rutas y adapta la interfaz

require_permission() corta la petición con un error 403 si falta el permiso. Va al principio del handler, con ?:

# use pagetop::prelude::*;
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
#     fn key(&self) -> CowStr { "board:post_notices".into() }
# }
async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> {
    require_permission(&request, &BoardPermission::PostNotices)?;
    Page::new(request)
        .with_title(Lc::n("New notice"))
        .render()
        .await
}

has_permission() devuelve un bool, para mostrar u ocultar lo que no se puede usar:

# use pagetop::prelude::*;
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
#     fn key(&self) -> CowStr { "board:post_notices".into() }
# }
async fn board(request: HttpRequest) -> Result<Markup, ErrorPage> {
    let can_post = has_permission(&request, &BoardPermission::PostNotices);
    let mut page = Page::new(request)
        .with_title(Lc::n("Garden board"))
        .with_child(Html::with(|_| html! { p { "The water tank is full." } }));
    if can_post {
        page = page.with_child(Button::anchor(Lc::n("Post a notice"), "/notices/new"));
    }
    page.render().await
}

Y dentro de un componente, cx.current_user() dice quién está viendo la página:

# use pagetop::prelude::*;
# fn f() -> Html {
Html::with(|cx| {
    let user = cx.current_user();
    html! {
        @if let Some(name) = user.display_name() {
            p { "Hello, " (name) "." }
        }
    }
})
# }

Ocultar el botón no basta: la ruta debe comprobar el permiso igualmente, porque cualquiera puede escribir la URL.

6. Asigna el permiso

Inicia sesión como admin y entra en Administración desde el menú de cuenta. En la lista de roles, abre los permisos de uno de ellos: verás el grupo «Garden board» con su permiso. Puedes concederlo:

  • al rol authenticated, para todos los usuarios que inicien sesión;
  • o a un rol nuevo («Gardeners», por ejemplo), y asignar ese rol a las cuentas que quieras.

Los administradores tienen todos los permisos sin necesidad de asignarlos.

El ejemplo completo

use pagetop::prelude::*;
use pagetop_user::PermissionRegistry;
use pagetop_user::prelude::*;

#[derive(Clone, Copy, Debug)]
enum BoardPermission {
    PostNotices,
}

impl Permission for BoardPermission {
    fn key(&self) -> CowStr {
        match self {
            Self::PostNotices => "board:post_notices".into(),
        }
    }

    fn label(&self) -> Lc {
        Lc::n("Post notices on the board")
    }

    fn group(&self) -> &'static str {
        "board"
    }

    fn group_label(&self) -> Lc {
        Lc::n("Garden board")
    }
}

fn declare_permissions(registry: &mut PermissionRegistry) {
    registry.register(&BoardPermission::PostNotices);
}

struct Board;

#[async_trait]
impl Extension for Board {
    fn dependencies(&self) -> Vec<ExtensionRef> {
        vec![&pagetop_user::User]
    }

    fn actions(&self) -> Vec<ActionBox> {
        actions![DeclarePermissions::new(declare_permissions)]
    }

    async fn initialize(&self) -> Result<(), BoxError> {
        InRegion::Global(&CoreRegions::Header).add(TopBar::new());
        Ok(())
    }

    fn configure_router(&self, router: Router) -> Router {
        router
            .route("/", web::get(board))
            .route("/notices/new", web::get(new_notice))
    }
}

#[derive(AutoDefault, Clone, Debug)]
struct TopBar;

#[async_trait]
impl Component for TopBar {
    fn new() -> Self {
        Self
    }

    async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
        let brand = Brand::new()
            .with_title(Lc::n("Garden board"))
            .with_route(Route::from("/"));
        Ok(Navbar::brand_left(brand)
            .with_item(navbar::Item::nav(account_menu(cx)))
            .render(cx)
            .await)
    }
}

async fn board(request: HttpRequest) -> Result<Markup, ErrorPage> {
    let can_post = has_permission(&request, &BoardPermission::PostNotices);
    let mut page = Page::new(request)
        .with_title(Lc::n("Garden board"))
        .with_child(Html::with(|_| html! { p { "The water tank is full." } }));
    if can_post {
        page = page.with_child(Button::anchor(Lc::n("Post a notice"), "/notices/new"));
    }
    page.render().await
}

async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> {
    require_permission(&request, &BoardPermission::PostNotices)?;
    Page::new(request)
        .with_title(Lc::n("New notice"))
        .with_child(Html::with(|_| html! { p { "Write your notice here." } }))
        .render()
        .await
}

#[pagetop::main]
async fn main() -> std::io::Result<()> {
    Application::prepare(&Board).await.run().await
}

Comprueba

  1. Sin iniciar sesión, la portada no muestra Post a notice, y http://localhost:8080/notices/new responde con la página de acceso denegado (403).
  2. Inicia sesión como admin: aparece el botón y la página se abre.
  3. Crea una cuenta con el enlace «Crear una cuenta» del menú, concede el permiso al rol authenticated e inicia sesión con ella: también puede publicar.

Siguiente