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:
| Cartella | Funzione |
|---|---|
login | accesso |
logout | uscita |
registration | registrazione (widget del framework, non pagina custom) |
activation | attivazione via codice inviato per email |
recover | recupero password |
social | accesso con provider social |
session | gestione della sessione |
users | gestione 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()invendor/wolfgan/cms/services/kernel.php). Una chiamata senzaX-Requested-With, o conReferrer-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 dilibrary/gallery/system/init.php(01 §2). Dalla 3.1.3 le POST non la prendono più; Api::send()(vendor/hcore/api/Api.php) passaerrordaffTranslator::get_word_by_code()usando il testo stesso come codice: un testo che il dizionario non conosce diventa una riga segnaposto diff_international(is_new = 1, con il messaggio inword_code, che è unvarchar(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)
| Tabella | Ruolo |
|---|---|
access_users | quella attiva. Account, credenziali. L'admin è ID=1 nel seed |
access_groups, access_users_groups | gruppi e appartenenza |
anagraph | profilo persona, collegato via anagraph.ID_user |
cm_mod_security_users | seconda 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()invendor/wolfgan/auth/Auth.php): un account con un hash in un altro formato (MySQLPASSWORD(), WordPress) non entra e deve reimpostare la password col recupero. Tutte le scritture producono bcrypt: il recupero (updateAccessInfo()inhook.php, conAuth::hashPassword()), il campopassworddel modelloaccess(string:inBcryptinvendor/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, nonINSERT). - 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()eCms::env()leggono bucket diversi. Non sono intercambiabili. È uno degli errori più difficili da vedere leggendo il codice, perché la chiamata sbagliata non fallisce: restituiscenull, 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_userse profilo suanagraph. - 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_userssia suanagraph. In seguito la cambia solo con il selettore lingua. È la lingua in cui riceve email e notifiche: vedi 06 §2. hook.phpcontiene 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 inhook.local.php(10 §1).- Creato l'account,
jc_registration_submit()(modules/auth/contents/registration/index.php) lancia l'eventoon_registration_done:$accountportaID_user,ID_anagraphedemail,$datii consensi (newsletter,privacy), la lingua, l'IP, il browser, la data di nascita (dob) e inextrai campi che il progetto aggiunge al form con nomeextra[...]: 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.phplo svuota ($response["code"] = "") prima diApi::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 diNotifier::send()conAuth::erroreInvio(): quel metodo torna una stringa quando l'invio fallisce,truecon un solo servizio quando riesce, e l'array conerrorsolo quando i servizi sono più d'uno. Leggerlo senza normalizzare dà un500(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::loginspedisce un codice di 6 cifre e risponderequire: "2fa"(status428). Il widget di login mostra il campo del codice e al clic successivo rimanda username, password ecode; solo allora parte la sessione (o il token). Il widget del framework lo fa da solo; un login custom deve gestirerequire. - Canali. Email con il template del tema
themes/site/contents/email/auth/account_code.html(testisvc_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 ilNotifier: JoeSMTP sesms.joesmtpè configurato, altrimenti Twilio (06 §4). Consmsl'utente senza telefono riceve il codice per email; senza nessuno dei due,409. Fino alla 3.0.3 il template eraauth::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_expiredel dominio, default 300 s) con chiaveJC_APP_SECRET+ hash della password. Vale per la finestra corrente e la precedente; rigenerareJC_APP_SECRETinvalida 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
sudocon le credenziali superadmin del config non passa dal 2FA; gli account non ancora attivati ricevono il messaggio di attivazione, non un codice.
6. La sessione: i cookie, e la trappola del doppione
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:
- I parametri del cookie vanno impostati PRIMA di
session_start(), in un solo punto (cms_session_cookie_params()inconf/gallery/config.php). Impostarli dopo non cambia il cookie già emesso: ne fa nascere un secondo, omonimo, e il login smette di reggere. - Per cancellare un cookie serve una scadenza nel passato.
lifetime = 0produce un cookie di sessione, non una cancellazione. Domainfa parte dell'identità del cookie: per ripulire un browser già sporco vanno emesse entrambe le forme (con e senzaDomain).Securesi deduce dalla connessione (MOD_AUTH_COOKIE_SECUREper forzarlo): cablato atruefa scartare il cookie in HTTP, e in sviluppo il login non regge mai.SameSite = Lax(MOD_AUTH_COOKIE_SAMESITEper portarlo aNone, che serve solo se il sito viene incorporato in un iframe di terze parti).- Niente
Domainsulocalhoste sugli indirizzi IP: i browser scartano il cookie. SESSION_NAMEnon è un valore libero: è derivato dal dominio (PHPSESS_[terzo][secondo][AAAAMM],wwwomesso) 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, confrontarecookieParams(),cookieApply(),cookie_create()ecookie_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). VediIGIENE_SEGRETI.md; - se si cifrano dati (token di terze parti, credenziali), AES-256-GCM con chiave derivata da
JC_APP_SECRETvia HKDF, coninfodiversa per uso — così il segreto di un sottosistema non è quello di un altro.
⚠️
JC_APP_SECRETvive inconfig.remote.php. Rigenerare quel file rende illeggibile tutto ciò che è stato cifrato con esso. Va nel backup, e non si rigenera.