pagetop/extensions/pagetop-user/README.md
Manuel Cillero 5172da65d6 ✨ (user): Añade proveedores de autenticación
Otras extensiones pueden comprobar las credenciales del inicio de sesión
con un servicio externo (un directorio LDAP...): módulo público provider
(AuthProvider, ProviderHandle, AccountPolicy, DeclareAuthProviders),
tabla `user_identities`, sección `[user.login]` (sources, local_fallback
y strict, que sustituye a login_strict), estado AwaitingApproval y
acciones AfterSessionResolved, AfterUserStatusChanged y
AdminUserFormExtras.

Las reglas que protegen las cuentas son siempre de pagetop-user: sólo se
vincula una cuenta que un administrador ha permitido para esa persona,
nunca la de un administrador, y una caída del proveedor no bloquea a
nadie.

Añade el límite de fallos por identificador tecleado, guarda las
contraseñas en util::SecretStr, crea en una sola transacción las cuentas
de proveedor y documenta todos los elementos públicos del crate.
2026-11-12 23:13:58 +01:00

245 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div align="center">
<h1>PageTop User</h1>
<p>Gestión de usuarios, autenticación, roles y permisos para <strong>PageTop</strong>.</p>
[![Doc API](https://img.shields.io/docsrs/pagetop-user?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-user)
[![Crates.io](https://img.shields.io/crates/v/pagetop-user.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-user)
[![Descargas](https://img.shields.io/crates/d/pagetop-user.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-user)
[![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-user#licencia)
</div>
## Sobre PageTop
[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
configurables, basadas en HTML, CSS y JavaScript.
## Descripción general
Añade cuentas de usuario a una aplicación PageTop: registro, inicio de sesión con sesiones en la
base de datos, perfil propio, recuperación de contraseña y verificación del email por correo, y
control de acceso con roles y permisos. Incluye las páginas de administración de usuarios, roles y
permisos en el panel de administración del núcleo, hechas sólo con componentes del núcleo para que
funcionen con cualquier tema.
## Guía rápida
**Añade la dependencia** a tu `Cargo.toml`:
```toml
[dependencies]
pagetop-user = "..."
```
Los usuarios y las sesiones se guardan con `pagetop-seaorm`: la aplicación elige el motor de base
de datos con su *feature* (`postgres`, `mysql` o `sqlite`) y configura la conexión en la sección
`[database]`.
**Declara la extensión** como dependencia de tu aplicación o de la extensión que la requiera
(`&pagetop_user::User`, como en el ejemplo de más abajo). Al arrancar crea sus tablas y, si no hay
ninguna cuenta, el primer administrador, con los datos de `[user.seed]`:
```toml
[user.seed]
admin_username = "admin"
admin_email = "admin@example.com"
# Sin 'admin_password', se genera una aleatoria y se muestra una sola vez al crearlo.
```
**Protege tus rutas** con su acceso (`Access`): PageTop lo comprueba antes de llegar al *handler*
con los permisos que concede esta extensión, y a un usuario anónimo sin acceso le ofrece el inicio
de sesión. Dentro del *handler*, el usuario actual está en el contexto de cada `Page` al crearla
con `Page::new()`, y funciones del núcleo como `has_permission()` lo consultan para las
comprobaciones más concretas:
```rust,no_run
use pagetop::prelude::*;
use pagetop_user::prelude::*;
#[derive(Clone, Copy, Debug)]
enum MyPermission {
SeeDashboard,
}
impl Permission for MyPermission {
fn key(&self) -> CowStr {
match self {
Self::SeeDashboard => "myapp:see_dashboard".into(),
}
}
}
struct MyApp;
#[async_trait]
impl Extension for MyApp {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_user::User]
}
fn configure_router(&self, routes: Routes) -> Routes {
routes.route(
"/dashboard",
Access::Permission(&MyPermission::SeeDashboard),
web::get(dashboard),
)
}
}
async fn dashboard(request: HttpRequest) -> Result<Markup, ErrorPage> {
Page::new(request)
.with_child(Html::with(|_| html! { h1 { "Panel" } }))
.render().await
}
```
## Páginas
| Ruta | Uso |
|---------------------------|--------------------------------------------------------------|
| `/user/login` | Inicio de sesión, con el nombre de usuario o el email. |
| `/user/register` | Registro, si lo permite `allow_registration`. |
| `/user` | Perfil propio: editarlo, cambiar la contraseña o el email. |
| `/user/password/reset` | Recuperación de la contraseña por correo. |
| `/admin/user/users` | Administración de usuarios: alta, edición, roles, bloqueo... |
| `/admin/user/roles` | Administración de roles y de sus permisos. |
| `/admin/user/permissions` | Catálogo de los permisos que declaran las extensiones. |
## Nombres de usuario y email
Cada cuenta tiene un nombre de usuario y un email, obligatorios y únicos; se puede iniciar sesión
con cualquiera de los dos. Qué nombres de usuario se aceptan lo decide `identity_policy` en la
sección `[user]`:
```toml
[user]
identity_policy = "unicode" # "strict" (por defecto), "unicode" o "permissive".
```
Con cualquier política, un nombre de usuario nunca contiene `@`, no se distinguen mayúsculas (`Ana`
y `ana` son el mismo usuario) y no se admiten nombres que se confunden a simple vista con otro
existente (`rnaria` si existe `maria`, o `аdmin` con una `а` cirílica). Las reglas completas de
cada política, y las del email, están en `IdentityPolicy` (módulo `config`).
## Proveedores de autenticación
Otras extensiones pueden comprobar las credenciales del inicio de sesión con un servicio externo,
como un directorio LDAP o Active Directory. Cada una declara su proveedor con la acción
`DeclareAuthProviders`, y la configuración decide con qué fuentes, y en qué orden, se comprueban
las credenciales. Por ejemplo, las dos, primero el directorio y después la contraseña local:
```toml
[user.login]
sources = ["ldap", "local"]
```
O sólo el directorio, salvo los administradores, que conservan su contraseña local como acceso de
emergencia por si el directorio no responde (`local_fallback` sólo se aplica cuando `"local"` no
está en `sources`):
```toml
[user.login]
sources = ["ldap"]
local_fallback = "admins"
```
Los límites de intentos, el bloqueo de cuentas, el estado de cada cuenta y las sesiones son los de
`pagetop-user` para todas las fuentes. Una cuenta vinculada a un proveedor sólo se autentica con él,
y lo que su titular puede cambiar (contraseña, email, datos del perfil, roles) lo decide el
proveedor. La contraseña tecleada nunca se guarda ni se escribe en las trazas: el proveedor sólo la
recibe para comprobarla (`pagetop::util::SecretStr`).
Las operaciones que crean cuentas, las vinculan con su identidad externa o cambian sus roles no son
funciones públicas: son métodos de un `ProviderHandle` que sólo
`pagetop-user` construye y que entrega a cada proveedor activo. Así sus reglas viven en un único
sitio: un proveedor sólo actúa sobre sus propias cuentas, una cuenta existente sólo se vincula si un
administrador lo ha permitido en su ficha (y nunca la de un administrador), y nadie puede conceder
el acceso total. Protege de errores en un proveedor, no de código malicioso compilado en la misma
aplicación. Los detalles están en el módulo `provider`.
## Correos
La recuperación de contraseña, la confirmación de una nueva dirección y, con
`require_email_verification`, la verificación de las cuentas nuevas envían un correo con un enlace
de un solo uso mediante `pagetop-mail`. Además, se avisa a la dirección de la cuenta cuando
cambia su contraseña (la cambie el usuario o un administrador) y cuando se pide cambiar su
dirección. Configura el envío en la sección `[mail]`, incluidos el remitente (`mail.from`), que
estos correos no indican, y la URL pública de los enlaces (`mail.base_url`): sin configurar, los
correos se escriben en las trazas en lugar de enviarse.
La recuperación de contraseña sólo se envía a cuentas activas. Mientras una dirección no está
verificada podría ser de otra persona, así que sus correos no incluyen nada que elija quien creó
la cuenta, ni el nombre de usuario ni el nombre visible. Una dirección queda verificada al
confirmarla desde el enlace del correo de verificación (abrirlo no basta: hay que pulsar un botón,
porque los servidores de correo abren los enlaces para analizarlos) o cuando la fija un
administrador.
Para cambiar su dirección, el usuario indica la nueva y su contraseña actual. La nueva no se aplica
hasta que se confirma desde el enlace que se le envía, y entonces queda verificada; mientras tanto,
la cuenta conserva la anterior, que recibe un aviso. Restablecer la contraseña descarta el cambio
pendiente: es lo que el aviso pide hacer a quien no lo ha pedido. También lo descarta un
administrador que fije otra dirección. Cada enlace sirve sólo para la dirección a la que se envió,
y los enlaces sin usar de recuperación y de verificación dejan de valer cuando cambia la dirección
de la cuenta; los de recuperación, también cuando cambia su contraseña.
Cambiar la contraseña o el email exige la contraseña actual, y sus fallos cuentan para el bloqueo
por intentos fallidos (`max_failed_logins`), como los del inicio de sesión.
Para que nadie pueda usar la aplicación para enviar correos a direcciones ajenas, las recuperaciones
de contraseña y los cambios de dirección se limitan por cuenta (`max_password_resets` y
`max_email_changes`), y ellos y los registros, también por dirección IP (`max_ip_requests`).
Los inicios de sesión fallidos se limitan también por dirección IP (`max_ip_failed_logins`), para
frenar a quien prueba unas pocas contraseñas habituales en muchas cuentas sin llegar a bloquear
ninguna. Detrás de un *proxy* inverso, los límites por IP requieren configurar
`server.client_ip_header`.
## Cookies
Al iniciar sesión se crea la *cookie* de sesión (`cookie_name` de `[user.session]`, `pagetop` por
defecto). Es propia, `HttpOnly` y con un identificador aleatorio que la aplicación guarda en la base
de datos. Se borra al cerrar sesión. Con `secure_cookies` de `[server]` activado, como debe estar si
la aplicación se sirve por HTTPS, sólo viaja por HTTPS.
Sin marcar "Recuérdame", el navegador la borra al cerrarse, y la sesión deja de valer tras
`idle_secs` sin uso. Es una *cookie* de autenticación para un servicio que el propio usuario pide,
así que en España y en la Unión Europea no requiere su aceptación: las normas y guías en que se basa
están en la sección *Cookies* del módulo `web` de PageTop.
Con "Recuérdame", la sesión se conserva aunque se cierre el navegador, hasta `remember_idle_secs`
sin uso (14 días por defecto). El dictamen 04/2012 del Grupo de Trabajo del Artículo 29 (WP194) no
exime estas *cookies* de inicio de sesión persistente, pero considera suficiente que sea el usuario
quien la pida marcando expresamente la casilla, siempre que sepa que se usa una *cookie*. Por eso el
formulario de acceso lo indica en el texto de ayuda de la casilla, que además desaconseja marcarla
en un equipo compartido. La aplicación sólo tiene que declararla también en su política de
*cookies*.
## Créditos
Este *crate* guarda las contraseñas con el algoritmo Argon2 mediante
[argon2](https://github.com/RustCrypto/password-hashes), de RustCrypto, y detecta los nombres de
usuario que se confunden con otro con
[unicode-security](https://github.com/unicode-rs/unicode-security). Ambos se distribuyen bajo
licencia MIT o Apache 2.0, a elegir.
## Advertencia
**PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos
hasta que se libere la versión **1.0.0**.
## Licencia
El código está disponible bajo una doble licencia:
* **Licencia MIT**
([LICENSE-MIT](LICENSE-MIT) o también https://opensource.org/licenses/MIT)
* **Licencia Apache, Versión 2.0**
([LICENSE-APACHE](LICENSE-APACHE) o también https://www.apache.org/licenses/LICENSE-2.0)
Puedes elegir la licencia que prefieras. Este enfoque de doble licencia es el estándar de facto en
el ecosistema Rust.