Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 08

Authentification, utilisateurs et permissions

Le CMS embarque un système de comptes complet : connexion, inscription, récupération du mot de passe, activation, connexion sociale, groupes, profils et permissions granulaires jusqu'au nœud de contenu individuel. Un projet n'implémente pas la connexion : il l'utilise.

1. Le module auth

modules/auth/contents/ contient les pages du cycle de vie du compte :

DossierFonction
loginconnexion
logoutdéconnexion
registrationinscription (widget du framework, pas une page sur mesure)
activationactivation par un code envoyé par email
recoverrécupération du mot de passe
socialconnexion avec des fournisseurs sociaux
sessiongestion de la session
usersgestion des utilisateurs côté module

Le thème du front-end habille les pages dans themes/site/contents/{login,recover,activation,logout}/ et les templates email dans themes/site/contents/email/auth/. La configuration des widgets est dans themes/site/conf/settings.auth.php.

Le JS des widgets ne peut pas dépendre du thème. Un widget de vendor/wolfgan/auth/widgets/<nom>/ est aussi rendu hors du layout du CMS — un site avec sa propre coque publique monte $widget["html"], ["css"] et ["js"] où il veut, et ne charge généralement que jQuery. Une fonction du thème (themes/<thème>/javascript/root.js, que import.php génère pour chaque site) n'y est pas, et l'appeler provoque un ReferenceError qui arrête la fonction à la première ligne : le bouton cesse de répondre, sans rien sur la page qui l'explique. Si un widget veut utiliser un extra du thème, il l'appelle derrière typeof … === "function" et se passe du reste. Le thème peut remplacer template, CSS et script du widget en mettant index.html, style.css, script.js dans themes/<thème>/contents/<nom>/ : ce qu'il ne met pas, il l'hérite du widget.

Le bouton de connexion appelle hCore.auth.login(url, selector, elem, redirect) : elem est l'élément cliqué — l'onclick passe this — sur lequel le script réactive les commandes après une réponse négative, et le chemin de retour ({ret_url}) va en quatrième position. Jusqu'à la 1.6.2 les templates, y compris themes/site/contents/login/index.html, le passaient en troisième : une connexion refusée mourait dans la console (jQuery("/restricted")) sans afficher le message, et ?ret_url= se perdait. Le script (vendor/wolfgan/auth/widgets/login/script.js) n'accepte plus comme elem qu'un élément ou un id, mais une page de connexion copiée dans le thème avec l'ancien onclick doit être corrigée pour avoir le retour. Le widget de récupération du mot de passe lit ses textes dans le template, s'ils y sont : data-err-password, data-err-conferma, data-err-diverse sur #errorMsg, data-testo-codice sur le bouton, data-etichette (séparées par |) sur l'étiquette de robustesse ; sans eux, restent les textes italiens (vendor/wolfgan/auth/widgets/recover/script.js). Le template du thème (themes/site/contents/recover/index.html) les porte tous, avec des codes du dictionnaire (svc_rec_err_password, svc_rec_err_confirm, svc_reg_err_pw_match, svc_rec_reset_btn, svc_pw_strength) ; jusqu'à la 3.0.3 il n'en portait aucun, et la récupération était en italien dans toutes les langues. Les six cases du code ont le libellé {_svc_otp_digit} N pour les lecteurs d'écran.

Les messages du compte sont dans la langue de la page. Les erreurs que Auth::login() renvoie au formulaire (champs vides, identifiants erronés, compte pas encore activé, utilisateur introuvable), celle de Auth::request() pour un email non valide, celles des widgets de récupération et d'activation (code erroné, activation échouée) et le texte du SMS avec le code se trouvent dans Auth::text() ; les textes du 2FA dans Auth::text2FA() (vendor/wolfgan/auth/Auth.php). Ils sont en italien, anglais, français et espagnol ; une langue qui n'y est pas reçoit l'anglais. Ils ne sont pas dans le dictionnaire parce qu'ils doivent fonctionner sur toute installation sans lignes en base : c'est pourquoi Auth::text() est public, et un widget l'utilise au lieu d'écrire son propre message. Le lien du compte à activer passe par content_i18n_url("/attivazione") (/en/activation, /fr/attivazione) et suit le manifeste contents/i18n.php ; Auth::userArea() fait de même avec l'espace personnel (JC_USER_AREA_PATH), où mènent les boutons finaux de l'activation et de la récupération ainsi que la redirection de qui ouvre l'activation déjà connecté. Les deux messages que le script de connexion écrit lui-même (réponse sans erreur, service qui ne répond pas) sont choisis par hCore.auth.loginText() dans vendor/wolfgan/auth/widgets/login/script.js, en lisant <html lang>. Jusqu'à la 3.0.3 ils étaient tous en italien dans toutes les langues, et le 2FA en espagnol sortait en anglais. Deux choses à savoir pour une connexion faite sur mesure :

  • le formulaire envoie le POST à /login, sans préfixe : le noyau tire la langue du préfixe du Referer, et seulement pour les requêtes XHR (rewritePathInfo() dans vendor/wolfgan/cms/services/kernel.php). Un appel sans X-Requested-With, ou avec Referrer-Policy: no-referrer, reçoit les messages dans la langue par défaut ;
  • jusqu'à la 3.1.2 l'inscription en XHR (modules/auth/contents/registration/index.php), envoyée depuis une page qui a ses propres sections comme la page d'accueil, recevait le HTML de cette page et le compte n'était pas créé : le POST était intercepté par le raccourci XHR de library/gallery/system/init.php (01 §2). Depuis la 3.1.3 les POST ne le prennent plus ;
  • Api::send() (vendor/hcore/api/Api.php) fait passer error par ffTranslator::get_word_by_code() en utilisant le texte lui-même comme code : un texte que le dictionnaire ne connaît pas devient une ligne de substitution dans ff_international (is_new = 1, avec le message dans word_code, qui est un varchar(255)). Un nouveau message, lien compris, reste sous les 255 caractères.

⚠️ modules/auth/conf/routing_table.xml contient aussi des règles pour ^/oauth2/(.+), ^/apiserver/(.*) et ^/services/oauth2/(.+) : les dossiers de destination n'existent pas dans ce dépôt. Ce sont des règles héritées de l'upstream, inertes aujourd'hui — il n'y a pas de serveur OAuth2 fonctionnel à utiliser tel quel.

2. L'API de session

Auth::isLogged();              // bool
Auth::get();                   // tableau de session : ID, group, et les valeurs applicatives
Auth::get("user");             // objet utilisateur (acl_primary = groupe)

$auth = Auth::get();
$auth["chiave_applicativa"] = $valore;
Auth::set($auth);              // signature : set($valeur, $cle = null)

Au-dessus se trouve le helper de la plateforme, dans hook.php :

$ID = checkUserRights(true);   // true  → redirection vers /login si invité   (pages)
$ID = checkUserRights(false);  // false → renvoie 0                           (services : répondre en JSON)

checkUserRights() implémente aussi l'usurpation admin (cookie user-id-value + ?force_id=, admise seulement pour le groupe administrators). L'ID est celui des données personnelles (anagraph.ID, le même que Auth::get()["ID"]), et un ID usurpé ne vaut que s'il correspond à des données personnelles liées à un compte (anagraph.ID_user) : sinon la fonction revient à l'utilisateur connecté et efface le cookie, qu'on ne touche pas quand il n'est pas là.

⚠️ Piège : justement parce que l'usurpation existe, checkUserRights() peut renvoyer un utilisateur différent de celui connecté. Un contrôle du type « cet enregistrement est à moi » doit se faire sur l'ID renvoyé par la fonction, pas sur celui de la session — sinon, en usurpation, l'admin voit ses propres données au lieu de celles de l'utilisateur qu'il regarde.

3. Les deux tables d'utilisateurs (et celle qui compte)

TableRôle
access_userscelle qui est active. Comptes, identifiants. L'admin est ID=1 dans le seed
access_groups, access_users_groupsgroupes et appartenance
anagraphprofil de la personne, lié via anagraph.ID_user
cm_mod_security_usersseconde table d'utilisateurs legacy du module mod_security : elle existe, contient le même admin, n'est pas le chemin de connexion actif

Les sections backend users et groups (conf/gallery/manage/{users,groups}/) synchronisent access_users ↔ access_groups ↔ access_users_groups ↔ anagraph, avec des mots de passe bcrypt.

Deux notes opérationnelles :

  • Les mots de passe sont en bcrypt, un point c'est tout, ne serait-ce que parce que PASSWORD() de MySQL n'existe plus sur MySQL 8. La connexion n'accepte que bcrypt (Auth::verifyPassword() dans vendor/wolfgan/auth/Auth.php) : un compte avec un hash dans un autre format (MySQL PASSWORD(), WordPress) n'entre pas et doit réinitialiser son mot de passe par la récupération. Toutes les écritures produisent du bcrypt : la récupération (updateAccessInfo() dans hook.php, avec Auth::hashPassword()), le champ password du modèle access (string:inBcrypt dans vendor/hcore/anagraph/services/access.php), le backend des utilisateurs, l'inscription et l'installeur. L'admin ID=1 du seed (database.sql) a encore un hash dans l'ancien format, qui n'ouvre rien avec une connexion uniquement bcrypt : l'installeur le réécrit avec le mot de passe choisi (UPDATE, pas INSERT).
  • L'adresse email d'un compte n'est pas un champ comme un autre : la changer sans un flux de confirmation sur la nouvelle adresse permet de « déplacer » un compte vers un email non vérifié. Si le flux n'existe pas, le champ reste non modifiable par l'utilisateur.

4. Profils et permissions

Profils d'accès au backend

La protection de tout le backend est une seule règle dans modules/auth/conf/routing_table.xml / conf/modules/auth/ : restricted, avec <profiles>admin,data-entry</profiles> et process_next. Tout ce qui est sous /restricted est protégé par cette règle : il n'est pas nécessaire (et il ne faut pas) revérifier dans chaque contrôleur.

Permissions granulaires sur les sections

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() et Cms::env() lisent des buckets différents. Ils ne sont pas interchangeables. C'est l'une des erreurs les plus difficiles à voir en lisant le code, parce que le mauvais appel n'échoue pas : il renvoie null, et la permission se retrouve simplement refusée (ou accordée) sans raison apparente.

Les constantes AREA_* — 74 occurrences dans le code — sont résolues à l'exécution par Auth::env()/Cms::env(). Certaines ont leur valeur de plateforme dans hook.php (AREA_PUBLISHING_SHOW_PREVIEW, AREA_SEO_SHOW_MODIFY, MOD_SEC_PROFILING), qui ne les définit que si elles n'existent pas déjà. Un projet qui veut activer ou désactiver l'une de ces fonctions du backend la définit dans son config (themes/site/conf/config.remote.php), lu avant hook.php : la modifier dans hook.php ne dure pas, parce que la mise à jour le remplace.

Permissions sur le contenu

users_rel_vgallery lie utilisateur et nœud, avec héritage cascading : la permission sur un dossier descend sur ses enfants. C'est le mécanisme qui permet des rédactions à visibilité partielle.

library/gallery/system/adv_permission.php et init_permission.php contiennent le moteur des permissions avancées.

5. Inscription et espace utilisateur

  • L'inscription est passée au widget du framework (pas à une page sur mesure), avec le compte dans access_users et le profil dans anagraph.
  • Elle s'active/se désactive avec JC_REGISTRATION_ENABLE (choisi dans l'assistant).
  • Le chemin de l'espace personnel est JC_USER_AREA_PATH ; /area-utente n'est qu'un repli, pas une valeur fixe : le code ne doit pas le câbler.
  • Qui s'inscrit reçoit comme langue du profil celle de la page depuis laquelle il s'inscrit, aussi bien dans access_users que dans anagraph. Ensuite il ne la change qu'avec le sélecteur de langue. C'est la langue dans laquelle il reçoit emails et notifications : voir 06 §2.
  • hook.php contient les helpers applicatifs : registerUser(), updateUserInfo(), updateAccessInfo(), getUserByTokenLocal(), saveLocalToken(), checkSid()/getSid()/setSid(). C'est du code de la plateforme : les écouteurs d'un projet, comme celui ci-dessous, vont dans un module ou dans hook.local.php (10 §1).
  • Une fois le compte créé, jc_registration_submit() (modules/auth/contents/registration/index.php) lance l'événement on_registration_done : $account porte ID_user, ID_anagraph et email, $dati les consentements (newsletter, privacy), la langue, l'IP, le navigateur, la date de naissance (dob) et, dans extra, les champs que le projet ajoute au formulaire avec le nom extra[...] : le widget les envoie tels quels, sans qu'il faille le modifier. Le CMS n'enregistre nulle part le consentement aux offres ni les champs du projet : si le projet en a besoin (fiche client, liste marketing, questionnaire), il les écrit ici. Sans écouteurs, rien ne se passe.
    Auth::addEvent("on_registration_done", function (&$account, $dati) {
        // $dati["newsletter"] vaut true si la case était cochée
        // $dati["extra"]["..."] : vient du navigateur, à valider
    });

Le retour après la connexion. ?redirect= (connexion, inscription, activation, récupération, déconnexion) et ?ret_url= (connexion) disent où envoyer l'utilisateur une fois l'opération terminée. Ils viennent de l'adresse de la page, c'est-à-dire de qui a écrit le lien, et passent par Auth::redirectLocale() (vendor/wolfgan/auth/Auth.php) : seul un chemin du site est valable (/area-utente, /en/my-account?tab=2), sans espaces, guillemets, < > ni barres obliques inverses, et qui ne commence pas par // ou /\. Une adresse absolue, même de son propre domaine, est ignorée et le widget se comporte comme sans paramètre. Les scripts de connexion et de déconnexion appliquent la même règle dans le navigateur. Une connexion écrite sur mesure qui accepte une adresse de retour la fait passer par la même méthode : sinon, c'est un open redirect (?redirect=https://altro.sito) ou du code exécuté dans la page (?redirect=javascript:…).

Activation. Le widget activation (vendor/wolfgan/auth/widgets/activation/) envoie par email un code à 6 chiffres et ouvre l'écran où le saisir. Deux règles non négociables :

  • Le code ne revient jamais dans la réponse au navigateur. C'est le secret qui prouve l'accès à la boîte mail : index.php le vide ($response["code"] = "") avant Api::send(). Le widget n'en a pas besoin — il lit les chiffres dans les champs remplis par la personne qui a reçu l'email — et une page d'activation sur mesure ne doit pas l'y remettre par commodité de débogage : n'importe qui le lirait dans les outils de développement et activerait le compte d'un autre.
  • Si l'email ne part pas, la page le dit. Auth::request() normalise le résultat de Notifier::send() avec Auth::erroreInvio() : cette méthode renvoie une chaîne quand l'envoi échoue, true avec un seul service quand il réussit, et le tableau avec error seulement quand il y a plusieurs services. Le lire sans normaliser donne un 500 (ou une erreur vide dans le bon cas) au lieu du vrai message. Voir 06 §2.

5bis. Second facteur (2FA)

Désactivé par défaut. Il s'active avec une constante dans config.remote.php (l'installeur l'écrit vide) :

define("AUTH_2FA", "sms");   // "" = désactivé, "email" ou "sms"

ou par appel avec Auth::login($user, $pass, array("2FA" => "email")).

  • Le flux. Un identifiant et un mot de passe corrects n'ouvrent pas encore la session : Auth::login envoie un code à 6 chiffres et répond require: "2fa" (statut 428). Le widget de connexion affiche le champ du code et au clic suivant renvoie identifiant, mot de passe et code ; seulement alors la session (ou le token) démarre. Le widget du framework le fait tout seul ; une connexion sur mesure doit gérer require.
  • Canaux. Email avec le template du thème themes/site/contents/email/auth/account_code.html (textes svc_mail_2fa_* du dictionnaire), ou avec celui du module (vendor/wolfgan/auth/mailer/account_code.html, en anglais seulement) si le thème ne l'a pas ; SMS avec le Notifier : JoeSMTP si sms.joesmtp est configuré, sinon Twilio (06 §4). Avec sms, l'utilisateur sans téléphone reçoit le code par email ; sans aucun des deux, 409. Jusqu'à la 3.0.3 le template était auth::account_code.html, un nom que le Mailer ne résout pas : l'email du code ne pouvait pas partir (mailer_template_notfound, et la connexion répondait qu'il était impossible d'envoyer le code).
  • Le code n'est pas enregistré : c'est un HMAC de l'ID utilisateur et de la fenêtre temporelle (sa_expire du domaine, par défaut 300 s) avec la clé JC_APP_SECRET + hash du mot de passe. Il vaut pour la fenêtre courante et la précédente ; régénérer JC_APP_SECRET n'invalide que les codes en vol.
  • Limites. Un nouvel envoi au plus toutes les 60 s (le code précédent reste valide) ; après 5 codes erronés le 2FA de l'utilisateur est bloqué 15 minutes. L'état (sans secrets) est dans cache/auth-2fa/.
  • Exceptions. L'accès d'urgence sudo avec les identifiants superadmin de la config ne passe pas par le 2FA ; les comptes pas encore activés reçoivent le message d'activation, pas un code.

6. La session : les cookies, et le piège du doublon

Le détail complet — avec le symptôme, la cause et les sept règles qui en découlent — est dans ../documentazione/cms-ricetta-portabile.md §12. En résumé, ce qu'on ne peut pas oublier :

  1. Les paramètres du cookie doivent être définis AVANT session_start(), en un seul endroit (cms_session_cookie_params() dans conf/gallery/config.php). Les définir après ne change pas le cookie déjà émis : cela en fait naître un second, homonyme, et la connexion ne tient plus.
  2. Pour effacer un cookie il faut une expiration dans le passé. lifetime = 0 produit un cookie de session, pas un effacement.
  3. Domain fait partie de l'identité du cookie : pour nettoyer un navigateur déjà sale il faut émettre les deux formes (avec et sans Domain).
  4. Secure se déduit de la connexion (MOD_AUTH_COOKIE_SECURE pour le forcer) : figé à true, il fait rejeter le cookie en HTTP, et en développement la connexion ne tient jamais.
  5. SameSite = Lax (MOD_AUTH_COOKIE_SAMESITE pour le passer à None, qui ne sert que si le site est intégré dans une iframe tierce).
  6. Pas de Domain sur localhost ni sur les adresses IP : les navigateurs rejettent le cookie.
  7. SESSION_NAME n'est pas une valeur libre : il est dérivé du domaine (PHPSESS_[troisième][second][AAAAMM], www omis) parce que deux installations sous le même domaine parent partagent les cookies et qu'avec un nom fixe les sessions s'écrasent. Année et mois restent figés dans la constante : les recalculer déconnecterait tous les utilisateurs le premier de chaque mois.

vendor/wolfgan/auth/services/session.php est patché par rapport à l'upstream. Une mise à jour du vendor qui l'écraserait ramènerait le défaut : avant de le remplacer, comparer cookieParams(), cookieApply(), cookie_create() et cookie_destroy().

7. Sécurité applicative : quoi mettre dans un nouveau projet

Réglages éprouvés dans l'écosystème, à reporter :

  • mots de passe bcrypt (déjà le cas dans le backend utilisateurs) ;
  • CSRF double-submit avec token en cookie + champ caché sur les formulaires qui écrivent ;
  • rate limit sur la connexion et la récupération du mot de passe ;
  • cookies applicatifs avec la syntaxe tableau de setcookie() : depuis PHP 7.3 la vieille astuce '; samesite=Lax' ajoutée au chemin ne fonctionne plus ;
  • qui ne peut pas entrer ne doit pas savoir que la porte existe : un espace réservé répond 404, pas 403, aux non-autorisés, et l'entrée de menu n'apparaît pas ;
  • secrets hors des fichiers suivis : ils sont dans config.remote.php (0640). Voir IGIENE_SEGRETI.md ;
  • si on chiffre des données (tokens tiers, identifiants), AES-256-GCM avec une clé dérivée de JC_APP_SECRET via HKDF, avec un info différent par usage — ainsi le secret d'un sous-système n'est pas celui d'un autre.

⚠️ JC_APP_SECRET vit dans config.remote.php. Régénérer ce fichier rend illisible tout ce qui a été chiffré avec. Il va dans la sauvegarde, et on ne le régénère pas.