Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 08

Autenticazione, utenti e permessi

Il CMS porta con sé un sistema di account completo: login, registrazione, recupero password, attivazione, login social, gruppi, profili e permessi granulari fino al singolo nodo di contenuto. Un progetto non implementa il login: lo usa.

1. Il modulo auth

modules/auth/contents/ contiene le pagine del ciclo di vita dell'account:

CartellaFunzione
loginaccesso
logoutuscita
registrationregistrazione (widget del framework, non pagina custom)
activationattivazione via codice inviato per email
recoverrecupero password
socialaccesso con provider social
sessiongestione della sessione
usersgestione utenti lato modulo

Il tema del frontend rivest le pagine in themes/site/contents/{login,recover,activation,logout}/ e i template email in themes/site/contents/email/auth/. La configurazione dei widget sta in themes/site/conf/settings.auth.php.

Il JS dei widget non può dipendere dal tema. Un widget di vendor/wolfgan/auth/widgets/<nome>/ viene reso anche fuori dal layout del CMS — un sito con un guscio pubblico suo monta $widget["html"], ["css"] e ["js"] dove gli pare, e di solito carica solo jQuery. Una funzione del tema (themes/<tema>/javascript/root.js, che import.php genera per ogni sito) lì non c'è, e chiamarla è un ReferenceError che ferma la funzione alla prima riga: il pulsante smette di rispondere, senza niente in pagina che lo spieghi. Se un widget vuole usare un extra del tema, lo chiama dietro typeof … === "function" e fa a meno del resto. Il tema può sostituire template, CSS e script del widget mettendo index.html, style.css, script.js in themes/<tema>/contents/<nome>/: quello che non mette lo eredita dal widget.

Il pulsante del login chiama hCore.auth.login(url, selector, elem, redirect): elem è l'elemento cliccato — l'onclick passa this — su cui lo script riaccende i comandi dopo una risposta negativa, e il percorso di ritorno ({ret_url}) va al quarto posto. Fino alla 1.6.2 i template, compreso themes/site/contents/login/index.html, lo passavano al terzo: un accesso rifiutato moriva in console (jQuery("/restricted")) senza mostrare il messaggio, e ?ret_url= si perdeva. Lo script (vendor/wolfgan/auth/widgets/login/script.js) ora accetta come elem solo un elemento o un id, ma una pagina di login copiata nel tema col vecchio onclick va corretta per avere il ritorno. Il widget di recupero password legge i suoi testi dal template, se ci sono: data-err-password, data-err-conferma, data-err-diverse su #errorMsg, data-testo-codice sul pulsante, data-etichette (separate da |) sull'etichetta della robustezza; senza, restano quelli italiani (vendor/wolfgan/auth/widgets/recover/script.js). Il template del tema (themes/site/contents/recover/index.html) li porta tutti, con codici del dizionario (svc_rec_err_password, svc_rec_err_confirm, svc_reg_err_pw_match, svc_rec_reset_btn, svc_pw_strength); fino alla 3.0.3 non ne portava nessuno, e il recupero era in italiano in ogni lingua. Le sei caselle del codice hanno l'etichetta {_svc_otp_digit} N per i lettori di schermo.

I messaggi dell'account sono nella lingua della pagina. Gli errori che Auth::login() restituisce al form (campi vuoti, credenziali sbagliate, account non ancora attivato, utente non trovato), quello di Auth::request() per un'email non valida, quelli dei widget di recupero e attivazione (codice errato, attivazione non riuscita) e il testo dell'SMS con il codice stanno in Auth::text(); i testi del 2FA in Auth::text2FA() (vendor/wolfgan/auth/Auth.php). Sono in italiano, inglese, francese e spagnolo; una lingua che lì non c'è riceve l'inglese. Non stanno nel dizionario perché devono funzionare su ogni installazione senza righe a database: per questo Auth::text() è pubblico, e un widget lo usa invece di scrivere un messaggio suo. Il link dell'account da attivare passa da content_i18n_url("/attivazione") (/en/activation, /fr/attivazione) e segue il manifest contents/i18n.php; Auth::userArea() fa lo stesso con l'area personale (JC_USER_AREA_PATH), dove portano i pulsanti finali di attivazione e recupero e il redirect di chi apre l'attivazione già autenticato. I due messaggi che lo script del login scrive da sé (risposta senza errore, servizio che non risponde) li sceglie hCore.auth.loginText() in vendor/wolfgan/auth/widgets/login/script.js, leggendo <html lang>. Fino alla 3.0.3 erano tutti in italiano in qualunque lingua, e il 2FA in spagnolo usciva in inglese. Due cose da sapere per un login scritto su misura:

  • il form manda il POST a /login, senza prefisso: la lingua il kernel la ricava dal prefisso del Referer, e solo per le richieste XHR (rewritePathInfo() in vendor/wolfgan/cms/services/kernel.php). Una chiamata senza X-Requested-With, o con Referrer-Policy: no-referrer, riceve i messaggi nella lingua predefinita;
  • fino alla 3.1.2 la registrazione in XHR (modules/auth/contents/registration/index.php), mandata da una pagina con sezioni proprie come la home, riceveva l'HTML di quella pagina e l'account non veniva creato: la POST la intercettava la scorciatoia XHR di library/gallery/system/init.php (01 §2). Dalla 3.1.3 le POST non la prendono più;
  • Api::send() (vendor/hcore/api/Api.php) passa error da ffTranslator::get_word_by_code() usando il testo stesso come codice: un testo che il dizionario non conosce diventa una riga segnaposto di ff_international (is_new = 1, con il messaggio in word_code, che è un varchar(255)). Un messaggio nuovo, link compreso, resta sotto i 255 caratteri.

⚠️ modules/auth/conf/routing_table.xml contiene anche regole per ^/oauth2/(.+), ^/apiserver/(.*) e ^/services/oauth2/(.+): le cartelle di destinazione non esistono in questo repo. Sono regole ereditate dall'upstream, oggi inerti — non c'è un server OAuth2 funzionante da usare così com'è.

2. L'API di sessione

Auth::isLogged();              // bool
Auth::get();                   // array della sessione: ID, group, e i valori applicativi
Auth::get("user");             // oggetto utente (acl_primary = gruppo)

$auth = Auth::get();
$auth["chiave_applicativa"] = $valore;
Auth::set($auth);              // firma: set($valore, $chiave = null)

Sopra ci sta l'helper della piattaforma, in hook.php:

$ID = checkUserRights(true);   // true  → redirect a /login se guest   (pagine)
$ID = checkUserRights(false);  // false → ritorna 0                    (servizi: rispondi JSON)

checkUserRights() implementa anche l'impersonificazione admin (cookie user-id-value + ?force_id=, ammessa solo al gruppo administrators). L'ID è quello anagrafico (anagraph.ID, lo stesso di Auth::get()["ID"]), e un ID impersonato vale solo se è un'anagrafica collegata a un account (anagraph.ID_user): altrimenti la funzione torna all'utente entrato e cancella il cookie, che quando non c'è non si tocca.

⚠️ Trappola: proprio perché esiste l'impersonificazione, checkUserRights() può restituire un utente diverso da quello loggato. Un controllo del tipo "questo record è mio" va fatto sull'ID restituito dalla funzione, non su quello della sessione — altrimenti in impersonificazione l'admin vede la propria roba invece di quella dell'utente che sta guardando.

3. Le due tabelle utenti (e quella che conta)

TabellaRuolo
access_usersquella attiva. Account, credenziali. L'admin è ID=1 nel seed
access_groups, access_users_groupsgruppi e appartenenza
anagraphprofilo persona, collegato via anagraph.ID_user
cm_mod_security_usersseconda tabella utenti legacy del modulo mod_security: esiste, contiene lo stesso admin, non è il path di login attivo

Le sezioni di backend users e groups (conf/gallery/manage/{users,groups}/) sincronizzano access_users ↔ access_groups ↔ access_users_groups ↔ anagraph, con password bcrypt.

Due note operative:

  • Le password sono bcrypt e basta, anche perché PASSWORD() di MySQL su MySQL 8 non esiste più. Il login accetta solo bcrypt (Auth::verifyPassword() in vendor/wolfgan/auth/Auth.php): un account con un hash in un altro formato (MySQL PASSWORD(), WordPress) non entra e deve reimpostare la password col recupero. Tutte le scritture producono bcrypt: il recupero (updateAccessInfo() in hook.php, con Auth::hashPassword()), il campo password del modello access (string:inBcrypt in vendor/hcore/anagraph/services/access.php), backend utenti, registrazione e installer. L'admin ID=1 del seed (database.sql) ha ancora un hash nel formato vecchio, che col login solo bcrypt non apre nulla: l'installer lo riscrive con la password scelta (UPDATE, non INSERT).
  • L'indirizzo email di un account non è un campo qualunque: cambiarlo senza un flusso di conferma sul nuovo indirizzo significa poter "spostare" un account su un'email non verificata. Se il flusso non c'è, il campo resta non modificabile dall'utente.

4. Profili e permessi

Profili di accesso al backend

La protezione dell'intero backend è una regola sola in modules/auth/conf/routing_table.xml / conf/modules/auth/: restricted, con <profiles>admin,data-entry</profiles> e process_next. Tutto ciò che sta sotto /restricted è protetto da quella regola: non serve (e non si deve) ricontrollare in ogni controller.

Permessi granulari sulle sezioni

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() e Cms::env() leggono bucket diversi. Non sono intercambiabili. È uno degli errori più difficili da vedere leggendo il codice, perché la chiamata sbagliata non fallisce: restituisce null, e il permesso risulta semplicemente negato (o concesso) senza motivo apparente.

Le costanti AREA_* — 74 occorrenze nel codice — sono risolte a runtime da Auth::env()/Cms::env(). Alcune hanno il valore di piattaforma in hook.php (AREA_PUBLISHING_SHOW_PREVIEW, AREA_SEO_SHOW_MODIFY, MOD_SEC_PROFILING), che le definisce solo se non esistono già. Un progetto che vuole accendere o spegnere una di quelle funzioni del backend la definisce nel suo config (themes/site/conf/config.remote.php), letto prima di hook.php: modificarla dentro hook.php non dura, perché l'aggiornamento lo sostituisce.

Permessi sul contenuto

users_rel_vgallery collega utente e nodo, con ereditarietà cascading: il permesso su una cartella scende sui figli. È il meccanismo che permette redazioni con visibilità parziale.

library/gallery/system/adv_permission.php e init_permission.php contengono il motore dei permessi avanzati.

5. Registrazione e area utente

  • La registrazione è passata al widget del framework (non a una pagina custom), con account su access_users e profilo su anagraph.
  • Si accende/spegne con JC_REGISTRATION_ENABLE (scelto nel wizard).
  • Il percorso dell'area personale è JC_USER_AREA_PATH; /area-utente è solo un fallback, non un valore fisso: il codice non deve cablarlo.
  • Chi si registra riceve come lingua del profilo quella della pagina da cui si registra, sia su access_users sia su anagraph. In seguito la cambia solo con il selettore lingua. È la lingua in cui riceve email e notifiche: vedi 06 §2.
  • hook.php contiene gli helper applicativi: registerUser(), updateUserInfo(), updateAccessInfo(), getUserByTokenLocal(), saveLocalToken(), checkSid()/getSid()/setSid(). È codice della piattaforma: gli ascoltatori di un progetto, come quello qui sotto, vanno in un modulo o in hook.local.php (10 §1).
  • Creato l'account, jc_registration_submit() (modules/auth/contents/registration/index.php) lancia l'evento on_registration_done: $account porta ID_user, ID_anagraph ed email, $dati i consensi (newsletter, privacy), la lingua, l'IP, il browser, la data di nascita (dob) e in extra i campi che il progetto aggiunge al form con nome extra[...]: il widget li manda così come sono, senza toccarlo. Il CMS il consenso alle offerte e i campi del progetto non li salva da nessuna parte: se al progetto servono (scheda cliente, lista marketing, questionario), li scrive qui. Senza ascoltatori non succede niente.
    Auth::addEvent("on_registration_done", function (&$account, $dati) {
        // $dati["newsletter"] è true se la casella era spuntata
        // $dati["extra"]["..."]: arriva dal browser, va validato
    });

Il ritorno dopo l'accesso. ?redirect= (login, registrazione, attivazione, recupero, logout) e ?ret_url= (login) dicono dove mandare l'utente a operazione conclusa. Arrivano dall'indirizzo della pagina, cioè da chi ha scritto il link, e passano da Auth::redirectLocale() (vendor/wolfgan/auth/Auth.php): vale solo un percorso del sito (/area-utente, /en/my-account?tab=2), senza spazi, apici, < > o barre rovesciate, e che non comincia con // o /\. Un indirizzo assoluto, anche del proprio dominio, viene ignorato e il widget si comporta come senza parametro. Gli script di login e logout applicano la stessa regola nel browser. Un login scritto su misura che accetta un indirizzo di ritorno lo fa passare dallo stesso metodo: senza, è un open redirect (?redirect=https://altro.sito) o codice eseguito nella pagina (?redirect=javascript:…).

Attivazione. Il widget activation (vendor/wolfgan/auth/widgets/activation/) manda per email un codice di 6 cifre e apre la schermata in cui inserirlo. Due regole che non si negoziano:

  • Il codice non torna mai nella risposta al browser. È il segreto che prova l'accesso alla casella: index.php lo svuota ($response["code"] = "") prima di Api::send(). Il widget non ne ha bisogno — legge le cifre dai campi che compila chi ha ricevuto l'email — e una pagina di attivazione scritta su misura non deve rimetterlo lì per comodità di debug: chiunque lo leggerebbe negli strumenti per sviluppatori e attiverebbe un account altrui.
  • Se l'email non parte, la pagina lo dice. Auth::request() normalizza l'esito di Notifier::send() con Auth::erroreInvio(): quel metodo torna una stringa quando l'invio fallisce, true con un solo servizio quando riesce, e l'array con error solo quando i servizi sono più d'uno. Leggerlo senza normalizzare dà un 500 (o un errore vuoto sul caso buono) invece del messaggio vero. Vedi 06 §2.

5bis. Secondo fattore (2FA)

Spento di default. Si accende con una costante in config.remote.php (l'installer la scrive vuota):

define("AUTH_2FA", "sms");   // "" = spento, "email" oppure "sms"

oppure per singola chiamata con Auth::login($user, $pass, array("2FA" => "email")).

  • Il flusso. Username e password giusti non aprono ancora la sessione: Auth::login spedisce un codice di 6 cifre e risponde require: "2fa" (status 428). Il widget di login mostra il campo del codice e al clic successivo rimanda username, password e code; solo allora parte la sessione (o il token). Il widget del framework lo fa da solo; un login custom deve gestire require.
  • Canali. Email con il template del tema themes/site/contents/email/auth/account_code.html (testi svc_mail_2fa_* del dizionario), o con quello del modulo (vendor/wolfgan/auth/mailer/account_code.html, solo inglese) se il tema non lo ha; SMS con il Notifier: JoeSMTP se sms.joesmtp è configurato, altrimenti Twilio (06 §4). Con sms l'utente senza telefono riceve il codice per email; senza nessuno dei due, 409. Fino alla 3.0.3 il template era auth::account_code.html, un nome che il Mailer non risolve: l'email del codice non poteva partire (mailer_template_notfound, e il login rispondeva «impossibile inviare il codice»).
  • Il codice non si salva: è un HMAC di ID utente e finestra temporale (sa_expire del dominio, default 300 s) con chiave JC_APP_SECRET + hash della password. Vale per la finestra corrente e la precedente; rigenerare JC_APP_SECRET invalida solo i codici in volo.
  • Limiti. Un nuovo invio al massimo ogni 60 s (il codice precedente resta valido); dopo 5 codici errati il 2FA dell'utente è bloccato per 15 minuti. Lo stato (niente segreti) è in cache/auth-2fa/.
  • Eccezioni. L'accesso di emergenza sudo con le credenziali superadmin del config non passa dal 2FA; gli account non ancora attivati ricevono il messaggio di attivazione, non un codice.

Il dettaglio completo — con il sintomo, la causa e le sette regole che ne discendono — è in ../documentazione/cms-ricetta-portabile.md §12. In sintesi, quello che non si può dimenticare:

  1. I parametri del cookie vanno impostati PRIMA di session_start(), in un solo punto (cms_session_cookie_params() in conf/gallery/config.php). Impostarli dopo non cambia il cookie già emesso: ne fa nascere un secondo, omonimo, e il login smette di reggere.
  2. Per cancellare un cookie serve una scadenza nel passato. lifetime = 0 produce un cookie di sessione, non una cancellazione.
  3. Domain fa parte dell'identità del cookie: per ripulire un browser già sporco vanno emesse entrambe le forme (con e senza Domain).
  4. Secure si deduce dalla connessione (MOD_AUTH_COOKIE_SECURE per forzarlo): cablato a true fa scartare il cookie in HTTP, e in sviluppo il login non regge mai.
  5. SameSite = Lax (MOD_AUTH_COOKIE_SAMESITE per portarlo a None, che serve solo se il sito viene incorporato in un iframe di terze parti).
  6. Niente Domain su localhost e sugli indirizzi IP: i browser scartano il cookie.
  7. SESSION_NAME non è un valore libero: è derivato dal dominio (PHPSESS_[terzo][secondo][AAAAMM], www omesso) perché due installazioni sotto lo stesso dominio padre condividono i cookie e con un nome fisso le sessioni si scavalcano. Anno e mese restano congelati nella costante: ricalcolarli scollegherebbe tutti gli utenti il primo di ogni mese.

vendor/wolfgan/auth/services/session.php è patchato rispetto all'upstream. Un aggiornamento del vendor che lo sovrascriva riporta il difetto: prima di sostituirlo, confrontare cookieParams(), cookieApply(), cookie_create() e cookie_destroy().

7. Sicurezza applicativa: cosa mettere in un progetto nuovo

Impostazioni collaudate nell'ecosistema, da riportare:

  • password bcrypt (già così nel backend utenti);
  • CSRF double-submit con token in cookie + campo nascosto sui form che scrivono;
  • rate limit su login e recupero password;
  • cookie applicativi con la sintassi ad array di setcookie(): da PHP 7.3 il vecchio trucco '; samesite=Lax' appeso al path non funziona più;
  • chi non può entrare non deve sapere che la porta esiste: un'area riservata risponde 404, non 403, ai non autorizzati, e la voce di menu non compare;
  • segreti fuori dai file tracciati: stanno in config.remote.php (0640). Vedi IGIENE_SEGRETI.md;
  • se si cifrano dati (token di terze parti, credenziali), AES-256-GCM con chiave derivata da JC_APP_SECRET via HKDF, con info diversa per uso — così il segreto di un sottosistema non è quello di un altro.

⚠️ JC_APP_SECRET vive in config.remote.php. Rigenerare quel file rende illeggibile tutto ciò che è stato cifrato con esso. Va nel backup, e non si rigenera.