Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 08

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:

CarpetaFunción
loginacceso
logoutsalida
registrationregistro (widget del framework, no página a medida)
activationactivación mediante código enviado por email
recoverrecuperación de contraseña
socialacceso con proveedores sociales
sessiongestión de la sesión
usersgestió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() en vendor/wolfgan/cms/services/kernel.php). Una llamada sin X-Requested-With, o con Referrer-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 de library/gallery/system/init.php (01 §2). Desde la 3.1.3 los POST ya no lo toman;
  • Api::send() (vendor/hcore/api/Api.php) pasa error por ffTranslator::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 en ff_international (is_new = 1, con el mensaje en word_code, que es un varchar(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)

TablaFunción
access_usersla activa. Cuentas, credenciales. El admin es ID=1 en el seed
access_groups, access_users_groupsgrupos y pertenencia
anagraphperfil de persona, vinculado vía anagraph.ID_user
cm_mod_security_userssegunda 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() en vendor/wolfgan/auth/Auth.php): una cuenta con un hash en otro formato (MySQL PASSWORD(), WordPress) no entra y tiene que restablecer la contraseña con la recuperación. Todas las escrituras producen bcrypt: la recuperación (updateAccessInfo() en hook.php, con Auth::hashPassword()), el campo password del modelo access (string:inBcrypt en vendor/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, no INSERT).
  • 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() y Cms::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: devuelve null, 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_users y el perfil en anagraph.
  • Se enciende/apaga con JC_REGISTRATION_ENABLE (elegido en el asistente).
  • La ruta del área personal es JC_USER_AREA_PATH; /area-utente es 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_users como en anagraph. Después lo cambia solo con el selector de idioma. Es el idioma en el que recibe emails y notificaciones: ver 06 §2.
  • hook.php contiene 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 en hook.local.php (10 §1).
  • Creada la cuenta, jc_registration_submit() (modules/auth/contents/registration/index.php) lanza el evento on_registration_done: $account lleva ID_user, ID_anagraph y email, $dati los consentimientos (newsletter, privacy), el idioma, la IP, el navegador, la fecha de nacimiento (dob) y, en extra, los campos que el proyecto añade al formulario con nombre extra[...]: 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.php lo vacía ($response["code"] = "") antes de Api::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 de Notifier::send() con Auth::erroreInvio(): ese método devuelve una cadena cuando el envío falla, true con un solo servicio cuando tiene éxito, y el array con error solo cuando hay varios servicios. Leerlo sin normalizar da un 500 (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::login envía un código de 6 cifras y responde require: "2fa" (status 428). El widget de login muestra el campo del código y en el clic siguiente vuelve a enviar usuario, contraseña y code; solo entonces arranca la sesión (o el token). El widget del framework lo hace solo; un login a medida debe gestionar require.
  • Canales. Email con la plantilla del tema themes/site/contents/email/auth/account_code.html (textos svc_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 el Notifier: JoeSMTP si sms.joesmtp está configurado, si no Twilio (06 §4). Con sms el usuario sin teléfono recibe el código por email; sin ninguno de los dos, 409. Hasta la 3.0.3 la plantilla era auth::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_expire del dominio, por defecto 300 s) con clave JC_APP_SECRET + hash de la contraseña. Vale para la ventana actual y la anterior; regenerar JC_APP_SECRET invalida 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 sudo con 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:

  1. Los parámetros de la cookie deben fijarse ANTES de session_start(), en un solo punto (cms_session_cookie_params() en conf/gallery/config.php). Fijarlos después no cambia la cookie ya emitida: hace nacer una segunda, homónima, y el login deja de sostenerse.
  2. Para borrar una cookie hace falta una caducidad en el pasado. lifetime = 0 produce una cookie de sesión, no un borrado.
  3. Domain forma parte de la identidad de la cookie: para limpiar un navegador ya sucio hay que emitir ambas formas (con y sin Domain).
  4. Secure se deduce de la conexión (MOD_AUTH_COOKIE_SECURE para forzarlo): fijado a true hace descartar la cookie en HTTP, y en desarrollo el login nunca se sostiene.
  5. SameSite = Lax (MOD_AUTH_COOKIE_SAMESITE para llevarlo a None, que sirve solo si el sitio se incrusta en un iframe de terceros).
  6. Nada de Domain en localhost ni en las direcciones IP: los navegadores descartan la cookie.
  7. SESSION_NAME no es un valor libre: se deriva del dominio (PHPSESS_[tercero][segundo][AAAAMM], www omitido) 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.php está parcheado respecto al upstream. Una actualización del vendor que lo sobrescriba devuelve el defecto: antes de sustituirlo, comparar cookieParams(), cookieApply(), cookie_create() y cookie_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). Ver IGIENE_SEGRETI.md;
  • si se cifran datos (tokens de terceros, credenciales), AES-256-GCM con clave derivada de JC_APP_SECRET vía HKDF, con info distinta por uso — así el secreto de un subsistema no es el de otro.

⚠️ JC_APP_SECRET vive en config.remote.php. Regenerar ese archivo hace ilegible todo lo que se ha cifrado con él. Va en el backup, y no se regenera.