Autenticación, usuarios y permisos
El CMS trae consigo un sistema de cuentas completo: login, registro, recuperación de contraseña, activación, login social, grupos, perfiles y permisos granulares hasta el nodo de contenido individual. Un proyecto no implementa el login: lo usa.
1. El módulo auth
modules/auth/contents/ contiene las páginas del ciclo de vida de la cuenta:
| Carpeta | Función |
|---|---|
login | acceso |
logout | salida |
registration | registro (widget del framework, no página a medida) |
activation | activación mediante código enviado por email |
recover | recuperación de contraseña |
social | acceso con proveedores sociales |
session | gestión de la sesión |
users | gestión de usuarios del lado del módulo |
El tema del front-end reviste las páginas en themes/site/contents/{login,recover,activation,logout}/ y las plantillas de email en themes/site/contents/email/auth/. La configuración de los widgets está en themes/site/conf/settings.auth.php.
El JS de los widgets no puede depender del tema. Un widget de vendor/wolfgan/auth/widgets/<nombre>/ se renderiza también fuera del layout del CMS — un sitio con una estructura pública propia monta $widget["html"], ["css"] y ["js"] donde quiere, y normalmente carga solo jQuery. Una función del tema (themes/<tema>/javascript/root.js, que import.php genera para cada sitio) allí no está, y llamarla es un ReferenceError que detiene la función en la primera línea: el botón deja de responder, sin nada en la página que lo explique. Si un widget quiere usar un extra del tema, lo llama tras typeof … === "function" y prescinde del resto. El tema puede sustituir plantilla, CSS y script del widget poniendo index.html, style.css, script.js en themes/<tema>/contents/<nombre>/: lo que no pone lo hereda del widget.
El botón de acceso llama a hCore.auth.login(url, selector, elem, redirect): elem es el elemento pulsado — el onclick pasa this — sobre el que el script reactiva los controles tras una respuesta negativa, y la ruta de retorno ({ret_url}) va en cuarto lugar. Hasta la 1.6.2 las plantillas, incluida themes/site/contents/login/index.html, la pasaban en tercer lugar: un acceso rechazado moría en la consola (jQuery("/restricted")) sin mostrar el mensaje, y ?ret_url= se perdía. El script (vendor/wolfgan/auth/widgets/login/script.js) ahora acepta como elem solo un elemento o un id, pero una página de acceso copiada en el tema con el onclick antiguo debe corregirse para tener el retorno. El widget de recuperación de contraseña lee sus textos de la plantilla, si los hay: data-err-password, data-err-conferma, data-err-diverse en #errorMsg, data-testo-codice en el botón, data-etichette (separadas por |) en la etiqueta de robustez; sin ellos, quedan los italianos (vendor/wolfgan/auth/widgets/recover/script.js). La plantilla del tema (themes/site/contents/recover/index.html) los lleva todos, con códigos del diccionario (svc_rec_err_password, svc_rec_err_confirm, svc_reg_err_pw_match, svc_rec_reset_btn, svc_pw_strength); hasta la 3.0.3 no llevaba ninguno, y la recuperación estaba en italiano en todos los idiomas. Las seis casillas del código tienen la etiqueta {_svc_otp_digit} N para los lectores de pantalla.
Los mensajes de la cuenta salen en el idioma de la página. Los errores que Auth::login() devuelve al formulario (campos vacíos, credenciales incorrectas, cuenta aún no activada, usuario no encontrado), el de Auth::request() para un email no válido, los de los widgets de recuperación y activación (código erróneo, activación fallida) y el texto del SMS con el código están en Auth::text(); los textos del 2FA en Auth::text2FA() (vendor/wolfgan/auth/Auth.php). Están en italiano, inglés, francés y español; un idioma que no esté ahí recibe el inglés. No están en el diccionario porque deben funcionar en cualquier instalación sin filas en la base de datos: por eso Auth::text() es público, y un widget lo usa en lugar de escribir un mensaje propio. El enlace de la cuenta pendiente de activar pasa por content_i18n_url("/attivazione") (/en/activation, /fr/attivazione) y sigue el manifiesto contents/i18n.php; Auth::userArea() hace lo mismo con el área personal (JC_USER_AREA_PATH), adonde llevan los botones finales de activación y recuperación y la redirección de quien abre la activación ya autenticado. Los dos mensajes que el script del acceso escribe por su cuenta (respuesta sin error, servicio que no responde) los elige hCore.auth.loginText() en vendor/wolfgan/auth/widgets/login/script.js, leyendo <html lang>. Hasta la 3.0.3 estaban todos en italiano en cualquier idioma, y el 2FA en español salía en inglés. Dos cosas que saber para un acceso hecho a medida:
- el formulario envía el POST a
/login, sin prefijo: el kernel saca el idioma del prefijo del Referer, y solo en las peticiones XHR (rewritePathInfo()envendor/wolfgan/cms/services/kernel.php). Una llamada sinX-Requested-With, o conReferrer-Policy: no-referrer, recibe los mensajes en el idioma predeterminado; - hasta la 3.1.2 el registro por XHR (
modules/auth/contents/registration/index.php), enviado desde una página con secciones propias como la página de inicio, recibía el HTML de esa página y la cuenta no se creaba: el POST lo atrapaba el atajo XHR delibrary/gallery/system/init.php(01 §2). Desde la 3.1.3 los POST ya no lo toman; Api::send()(vendor/hcore/api/Api.php) pasaerrorporffTranslator::get_word_by_code()usando el propio texto como código: un texto que el diccionario no conoce se convierte en una fila de marcador de posición enff_international(is_new = 1, con el mensaje enword_code, que es unvarchar(255)). Un mensaje nuevo, enlace incluido, se queda por debajo de los 255 caracteres.
⚠️ modules/auth/conf/routing_table.xml contiene también reglas para ^/oauth2/(.+), ^/apiserver/(.*) y ^/services/oauth2/(.+): las carpetas de destino no existen en este repo. Son reglas heredadas del upstream, hoy inertes — no hay un servidor OAuth2 funcional que usar tal cual.
2. La API de sesión
Auth::isLogged(); // bool
Auth::get(); // array de la sesión: ID, group, y los valores de aplicación
Auth::get("user"); // objeto usuario (acl_primary = grupo)
$auth = Auth::get();
$auth["chiave_applicativa"] = $valore;
Auth::set($auth); // firma: set($valor, $clave = null)
Encima está el helper de la plataforma, en hook.php:
$ID = checkUserRights(true); // true → redirect a /login si es invitado (páginas)
$ID = checkUserRights(false); // false → devuelve 0 (servicios: responde JSON)
checkUserRights() implementa también la suplantación de admin (cookie user-id-value + ?force_id=, admitida solo al grupo administrators). El ID es el de los datos personales (anagraph.ID, el mismo de Auth::get()["ID"]), y un ID suplantado solo vale si corresponde a unos datos personales vinculados a una cuenta (anagraph.ID_user): si no, la función vuelve al usuario autenticado y borra la cookie, que no se toca cuando no está.
⚠️ Trampa: precisamente porque existe la suplantación,
checkUserRights()puede devolver un usuario distinto del conectado. Un control del tipo "este registro es mío" debe hacerse sobre el ID devuelto por la función, no sobre el de la sesión — si no, en suplantación el admin ve sus propias cosas en lugar de las del usuario que está mirando.
3. Las dos tablas de usuarios (y la que cuenta)
| Tabla | Función |
|---|---|
access_users | la activa. Cuentas, credenciales. El admin es ID=1 en el seed |
access_groups, access_users_groups | grupos y pertenencia |
anagraph | perfil de persona, vinculado vía anagraph.ID_user |
cm_mod_security_users | segunda tabla de usuarios legacy del módulo mod_security: existe, contiene el mismo admin, no es la ruta de login activa |
Las secciones de backend users y groups (conf/gallery/manage/{users,groups}/) sincronizan access_users ↔ access_groups ↔ access_users_groups ↔ anagraph, con contraseñas bcrypt.
Dos notas operativas:
- Las contraseñas son bcrypt y punto, también porque
PASSWORD()de MySQL ya no existe en MySQL 8. El acceso solo acepta bcrypt (Auth::verifyPassword()envendor/wolfgan/auth/Auth.php): una cuenta con un hash en otro formato (MySQLPASSWORD(), WordPress) no entra y tiene que restablecer la contraseña con la recuperación. Todas las escrituras producen bcrypt: la recuperación (updateAccessInfo()enhook.php, conAuth::hashPassword()), el campopassworddel modeloaccess(string:inBcryptenvendor/hcore/anagraph/services/access.php), el backend de usuarios, el registro y el instalador. El admin ID=1 del seed (database.sql) todavía tiene un hash en el formato antiguo, que con el acceso solo bcrypt no abre nada: el instalador lo reescribe con la contraseña elegida (UPDATE, noINSERT). - La dirección de email de una cuenta no es un campo cualquiera: cambiarla sin un flujo de confirmación en la nueva dirección significa poder "trasladar" una cuenta a un email no verificado. Si el flujo no existe, el campo sigue sin ser modificable por el usuario.
4. Perfiles y permisos
Perfiles de acceso al backend
La protección de todo el backend es una sola regla en modules/auth/conf/routing_table.xml / conf/modules/auth/: restricted, con <profiles>admin,data-entry</profiles> y process_next. Todo lo que está bajo /restricted está protegido por esa regla: no hace falta (y no se debe) volver a comprobar en cada controlador.
Permisos granulares sobre las secciones
Auth::env("AREA_VGALLERY_SHOW_MODIFY");
Auth::env("AREA_VGALLERY_SHOW_ADDNEW");
Auth::env("AREA_VGALLERY_SHOW_DELETE");
Auth::env("AREA_VGALLERY_SHOW_SEO");
Auth::env("AREA_VGALLERY_SHOW_PERMISSION");
⚠️
Auth::env()yCms::env()leen buckets distintos. No son intercambiables. Es uno de los errores más difíciles de ver leyendo el código, porque la llamada equivocada no falla: devuelvenull, y el permiso resulta simplemente denegado (o concedido) sin motivo aparente.
Las constantes AREA_* — 74 apariciones en el código — se resuelven en tiempo de ejecución con Auth::env()/Cms::env(). Algunas tienen su valor de plataforma en hook.php (AREA_PUBLISHING_SHOW_PREVIEW, AREA_SEO_SHOW_MODIFY, MOD_SEC_PROFILING), que las define solo si no existen ya. Un proyecto que quiera encender o apagar una de esas funciones del backend la define en su config (themes/site/conf/config.remote.php), leído antes que hook.php: cambiarla dentro de hook.php no dura, porque la actualización lo sustituye.
Permisos sobre el contenido
users_rel_vgallery vincula usuario y nodo, con herencia cascading: el permiso sobre una carpeta baja a los hijos. Es el mecanismo que permite redacciones con visibilidad parcial.
library/gallery/system/adv_permission.php e init_permission.php contienen el motor de los permisos avanzados.
5. Registro y área de usuario
- El registro ha pasado al widget del framework (no a una página a medida), con la cuenta en
access_usersy el perfil enanagraph. - Se enciende/apaga con
JC_REGISTRATION_ENABLE(elegido en el asistente). - La ruta del área personal es
JC_USER_AREA_PATH;/area-utentees solo un fallback, no un valor fijo: el código no debe fijarlo. - Quien se registra recibe como idioma del perfil el de la página desde la que se registra, tanto en
access_userscomo enanagraph. Después lo cambia solo con el selector de idioma. Es el idioma en el que recibe emails y notificaciones: ver 06 §2. hook.phpcontiene los helpers de aplicación:registerUser(),updateUserInfo(),updateAccessInfo(),getUserByTokenLocal(),saveLocalToken(),checkSid()/getSid()/setSid(). Es código de la plataforma: los listeners de un proyecto, como el de abajo, van en un módulo o enhook.local.php(10 §1).- Creada la cuenta,
jc_registration_submit()(modules/auth/contents/registration/index.php) lanza el eventoon_registration_done:$accountllevaID_user,ID_anagraphyemail,$datilos consentimientos (newsletter,privacy), el idioma, la IP, el navegador, la fecha de nacimiento (dob) y, enextra, los campos que el proyecto añade al formulario con nombreextra[...]: el widget los envía tal cual, sin necesidad de tocarlo. El CMS no guarda en ningún sitio el consentimiento a las ofertas ni los campos del proyecto: si el proyecto los necesita (ficha de cliente, lista de marketing, cuestionario), los escribe aquí. Sin oyentes no pasa nada.Auth::addEvent("on_registration_done", function (&$account, $dati) { // $dati["newsletter"] es true si la casilla estaba marcada // $dati["extra"]["..."]: llega del navegador, hay que validarlo });
La vuelta tras el acceso. ?redirect= (login, registro, activación, recuperación, logout) y ?ret_url= (login) dicen adónde mandar al usuario una vez terminada la operación. Llegan de la dirección de la página, es decir, de quien escribió el enlace, y pasan por Auth::redirectLocale() (vendor/wolfgan/auth/Auth.php): vale solo una ruta del sitio (/area-utente, /en/my-account?tab=2), sin espacios, comillas, < > ni barras invertidas, y que no empiece por // o /\. Una dirección absoluta, incluso del propio dominio, se ignora y el widget se comporta como sin parámetro. Los scripts de login y logout aplican la misma regla en el navegador. Un login hecho a medida que acepta una dirección de vuelta la hace pasar por el mismo método: sin él, es un open redirect (?redirect=https://altro.sito) o código ejecutado en la página (?redirect=javascript:…).
Activación. El widget activation (vendor/wolfgan/auth/widgets/activation/) envía por email un código de 6 cifras y abre la pantalla en la que introducirlo. Dos reglas no negociables:
- El código nunca vuelve en la respuesta al navegador. Es el secreto que prueba el acceso al buzón:
index.phplo vacía ($response["code"] = "") antes deApi::send(). El widget no lo necesita — lee las cifras de los campos que rellena quien ha recibido el email — y una página de activación hecha a medida no debe volver a ponerlo ahí por comodidad de depuración: cualquiera lo leería en las herramientas de desarrollo y activaría una cuenta ajena. - Si el email no sale, la página lo dice.
Auth::request()normaliza el resultado deNotifier::send()conAuth::erroreInvio(): ese método devuelve una cadena cuando el envío falla,truecon un solo servicio cuando tiene éxito, y el array conerrorsolo cuando hay varios servicios. Leerlo sin normalizar da un500(o un error vacío en el caso bueno) en lugar del mensaje verdadero. Ver 06 §2.
5bis. Segundo factor (2FA)
Apagado por defecto. Se enciende con una constante en config.remote.php (el instalador la escribe vacía):
define("AUTH_2FA", "sms"); // "" = apagado, "email" o "sms"
o por llamada con Auth::login($user, $pass, array("2FA" => "email")).
- El flujo. Usuario y contraseña correctos no abren aún la sesión:
Auth::loginenvía un código de 6 cifras y responderequire: "2fa"(status428). El widget de login muestra el campo del código y en el clic siguiente vuelve a enviar usuario, contraseña ycode; solo entonces arranca la sesión (o el token). El widget del framework lo hace solo; un login a medida debe gestionarrequire. - Canales. Email con la plantilla del tema
themes/site/contents/email/auth/account_code.html(textossvc_mail_2fa_*del diccionario), o con la del módulo (vendor/wolfgan/auth/mailer/account_code.html, solo en inglés) si el tema no la tiene; SMS con elNotifier: JoeSMTP sisms.joesmtpestá configurado, si no Twilio (06 §4). Consmsel usuario sin teléfono recibe el código por email; sin ninguno de los dos,409. Hasta la 3.0.3 la plantilla eraauth::account_code.html, un nombre que el Mailer no resuelve: el email del código no podía salir (mailer_template_notfound, y el acceso respondía que no se podía enviar el código). - El código no se guarda: es un HMAC de ID de usuario y ventana temporal (
sa_expiredel dominio, por defecto 300 s) con claveJC_APP_SECRET+ hash de la contraseña. Vale para la ventana actual y la anterior; regenerarJC_APP_SECRETinvalida solo los códigos en curso. - Límites. Un nuevo envío como máximo cada 60 s (el código anterior sigue siendo válido); tras 5 códigos erróneos el 2FA del usuario queda bloqueado 15 minutos. El estado (sin secretos) está en
cache/auth-2fa/. - Excepciones. El acceso de emergencia
sudocon las credenciales de superadmin del config no pasa por el 2FA; las cuentas aún no activadas reciben el mensaje de activación, no un código.
6. La sesión: las cookies, y la trampa del duplicado
El detalle completo — con el síntoma, la causa y las siete reglas que se derivan — está en ../documentazione/cms-ricetta-portabile.md §12. En síntesis, lo que no se puede olvidar:
- Los parámetros de la cookie deben fijarse ANTES de
session_start(), en un solo punto (cms_session_cookie_params()enconf/gallery/config.php). Fijarlos después no cambia la cookie ya emitida: hace nacer una segunda, homónima, y el login deja de sostenerse. - Para borrar una cookie hace falta una caducidad en el pasado.
lifetime = 0produce una cookie de sesión, no un borrado. Domainforma parte de la identidad de la cookie: para limpiar un navegador ya sucio hay que emitir ambas formas (con y sinDomain).Securese deduce de la conexión (MOD_AUTH_COOKIE_SECUREpara forzarlo): fijado atruehace descartar la cookie en HTTP, y en desarrollo el login nunca se sostiene.SameSite = Lax(MOD_AUTH_COOKIE_SAMESITEpara llevarlo aNone, que sirve solo si el sitio se incrusta en un iframe de terceros).- Nada de
Domainenlocalhostni en las direcciones IP: los navegadores descartan la cookie. SESSION_NAMEno es un valor libre: se deriva del dominio (PHPSESS_[tercero][segundo][AAAAMM],wwwomitido) porque dos instalaciones bajo el mismo dominio padre comparten las cookies y con un nombre fijo las sesiones se pisan. Año y mes quedan congelados en la constante: recalcularlos desconectaría a todos los usuarios el día uno de cada mes.
vendor/wolfgan/auth/services/session.phpestá parcheado respecto al upstream. Una actualización del vendor que lo sobrescriba devuelve el defecto: antes de sustituirlo, compararcookieParams(),cookieApply(),cookie_create()ycookie_destroy().
7. Seguridad de aplicación: qué poner en un proyecto nuevo
Ajustes probados en el ecosistema, para trasladar:
- contraseñas bcrypt (ya es así en el backend de usuarios);
- CSRF double-submit con token en cookie + campo oculto en los formularios que escriben;
- rate limit en login y recuperación de contraseña;
- cookies de aplicación con la sintaxis de array de
setcookie(): desde PHP 7.3 el viejo truco de'; samesite=Lax'añadido al path ya no funciona; - quien no puede entrar no debe saber que la puerta existe: un área reservada responde 404, no 403, a los no autorizados, y la entrada de menú no aparece;
- secretos fuera de los archivos rastreados: están en
config.remote.php(0640). VerIGIENE_SEGRETI.md; - si se cifran datos (tokens de terceros, credenciales), AES-256-GCM con clave derivada de
JC_APP_SECRETvía HKDF, coninfodistinta por uso — así el secreto de un subsistema no es el de otro.
⚠️
JC_APP_SECRETvive enconfig.remote.php. Regenerar ese archivo hace ilegible todo lo que se ha cifrado con él. Va en el backup, y no se regenera.