Multi-tenant : résolution d'un domaine vers un site (et isolation)¶
Cette page explique pourquoi Kirexo résout le domaine d'une requête vers un site à l'exécution plutôt qu'au routage statique, comment cette résolution distingue les trois natures de domaine, et pourquoi elle s'accompagne d'une double isolation qui garantit qu'aucune surface d'administration ni aucun cookie de session de l'application ne fuit sur le domaine public d'un utilisateur. Pour ce qu'un utilisateur peut réellement afficher sur son domaine, voir Pages spéciales du plugin web ; pour le socle à plugins et le worker mode qui contraignent ces choix, voir Architecture.
Le domaine d'un site n'est pas connu à l'avance¶
Chaque carnet peut avoir son propre site public — la configuration du site se fait carnet par carnet (voir Configuration par carnet et extensibilité des plugins). Un site naît quand on rattache un domaine à un carnet ; il est destiné à être servi sur ce domaine — blog.exemple.fr, notes.autrechose.org — un domaine que l'utilisateur choisit et branche lui-même, et que Kirexo ne connaît pas au moment où le code est écrit.
C'est ce qui interdit la solution Symfony la plus directe. Attacher une route à un hôte via #[Route(host: '…')] suppose de figer le domaine dans le code, à la compilation du routeur. Or ici l'ensemble des domaines valides est :
- dynamique — il grandit à chaque site créé, change à chaque domaine ajouté ou retiré ;
- inconnu à l'avance — il vit en base de données, pas dans les annotations ;
- potentiellement immense — autant d'entrées que de domaines mappés.
On ne peut donc pas router par le domaine ; on doit router après avoir résolu le domaine. La décision est reportée à l'exécution : à chaque requête, on lit l'en-tête Host et on décide quoi en faire.
Un aiguillage prioritaire sur kernel.request¶
La résolution est portée par un unique écouteur d'infrastructure, HostResolutionSubscriber (src/Plugin/Web/src/EventSubscriber/HostResolutionSubscriber.php), abonné à kernel.request. Sa priorité est le point clé : il s'exécute juste au-dessus du routeur de Symfony.
Le RouterListener de Symfony tourne à la priorité 32 et se court-circuite lui-même dès qu'un _controller est déjà posé sur la requête — dans ce cas, il considère que le routage a déjà eu lieu et ne fait rien. En s'insérant à la priorité 33, HostResolutionSubscriber passe avant lui et peut, pour un domaine de site, poser lui-même le contrôleur cible. Le routage applicatif normal (les routes app_*) est alors totalement contourné, sans qu'on ait eu à le désactiver.
L'en-tête Host a par ailleurs déjà été validé plus tôt dans la chaîne : un Host mal formé y est rejeté en 400, et, là où trusted_hosts est défini (dev, CI), un Host hors de la regex aussi. En production, aucune regex n'est posée, pour des raisons détaillées plus bas. Le firewall s'exécute plus bas : il verra donc les attributs que le subscriber aura posés.
Trois cas, une seule requête¶
À chaque requête principale, l'aiguillage tranche entre trois natures de domaine.
- Domaine réservé à l'application — c'est un domaine de Kirexo lui-même (l'apex, le sous-domaine d'admin,
localhosten dev). Le subscriber ne fait rien et rend la main : le routageapp_*reprend son cours normal, zéro changement de comportement. La liste de ces domaines vient de la configuration (voirKIREXO_RESERVED_DOMAINS). - Domaine mappé à un site — le domaine est trouvé en base comme rattaché à un site. Le subscriber réécrit la cible interne (le contrôleur public du plugin web) sans toucher à l'URL, et marque la requête comme « site public » (voir plus bas).
- Domaine inconnu — ni réservé, ni mappé. Le subscriber lève une
NotFoundHttpException: un domaine qui pointe vers Kirexo sans y correspondre reçoit un 404, pas une page d'accueil par défaut.
Le tout se décide en amont du routeur, dans l'ordre : domaine app d'abord (le cas le plus fréquent et le moins coûteux, aucune requête base), puis résolution en base, puis 404.
flowchart TD
A["kernel.request (requête principale)<br/>HostResolutionSubscriber @33"] --> B{"Host réservé à l'app ?<br/>(KIREXO_RESERVED_DOMAINS)"}
B -- oui --> C["on rend la main<br/>→ RouterListener @32<br/>→ routage app_* normal"]
B -- non --> D{"Domaine mappé à un site ?<br/>(lecture en base)"}
D -- "non (inconnu)" --> E["404<br/>NotFoundHttpException"]
D -- "oui" --> F["état passif du domaine<br/>en attente → actif (throttlé)"]
F --> G["requête marquée « site public »"]
G --> H["cible interne réécrite<br/>(routes publiques du plugin web)"]
H --> I["RouterListener @32 court-circuité<br/>→ rendu du site, URL inchangée"]
Pourquoi pas de sous-requête¶
Pour servir le site, une approche classique serait de déclencher une sous-requête (HttpKernel::handle avec un nouveau Request) vers le contrôleur du site. Kirexo l'écarte volontairement.
Une sous-requête crée un nouvel objet Request : on perd l'identité de la requête d'origine, on re-résout la session et la locale, et on retraverse une partie de la pile du kernel. En worker mode FrankenPHP, où l'interpréteur reste chargé entre les requêtes et où l'on cherche à garder un chemin de requête minimal, ce double passage est un coût inutile à chaque page vue d'un site.
Kirexo garde donc la requête principale et se contente de réorienter son contrôleur cible : on remplace les attributs de routage (_controller, _route, et les paramètres comme le slug de page) sur l'objet existant. L'URL affichée dans le navigateur ne change pas — le visiteur voit blog.exemple.fr/ma-page, pas une URL interne de l'application — et aucune sous-requête n'est engagée.
La double isolation : « admin ≠ publication » jusque dans le réseau¶
Le point de sécurité structurant est qu'un domaine de site ne doit jamais laisser passer une surface d'administration, de connexion ou d'espace utilisateur — ni la servir, ni même émettre un cookie de session de l'application. C'est le prolongement réseau de l'invariant « admin ≠ publication » : l'administration gère les comptes, jamais le contenu public, et un domaine public ne doit rien exposer de l'administration. Deux couches indépendantes le garantissent, en défense en profondeur.
Couche 1 — un routage restreint aux seules pages publiques¶
Sur un domaine de site, la réécriture de cible ne passe pas par le routeur applicatif complet. Elle passe par un matcher restreint qui ne connaît que les routes publiques du plugin web (préfixe de nommage web_plugin_public_* : accueil du site, page spéciale, article, sonde de santé). Les routes app_login, app_admin_*, la bascule entre espaces, l'espace utilisateur… n'existent tout simplement pas pour ce matcher.
La conséquence est nette : sur blog.exemple.fr, demander /login ou /admin ne renvoie pas un 403 (« ça existe mais pas pour toi ») — cela renvoie un 404, parce que ces chemins ne correspondent à aucune page atteignable. Ce n'est pas une autorisation refusée, c'est une surface qui n'existe pas sur ce domaine. C'est le même parti pris de discrétion que celui décrit dans Architecture des firewalls.
Couche 2 — un firewall « sans sécurité » dédié¶
Même verrouillé côté routage, un domaine de site ne doit jamais émettre un cookie de session applicatif, un token d'authentification ni un cookie remember-me de Kirexo. Sinon un visiteur anonyme d'un blog repartirait avec un cookie de session de la plateforme — une fuite de contexte d'authentification entre un site public et l'application.
Kirexo l'empêche avec un firewall dédié en mode « sans sécurité » (security: false), déclaré en tête de config/packages/security.yaml, avant les firewalls admin et user. Un firewall security: false n'installe aucun authenticator et ne pose aucun jeton de session : sur un domaine de site, la sécurité de l'application est tout simplement absente du circuit.
Ce firewall se déclenche sur un drapeau générique posé sur la requête par le subscriber (un attribut « cette requête est un site public »). Ce drapeau vit dans le cœur de l'application, pas dans le plugin : c'est un choix d'architecture délibéré. Faire référence à une classe du plugin depuis security.yaml coupleraient la configuration de sécurité du cœur au plugin — retirer le plugin casserait alors la sécurité de l'application, ce qui violerait le principe « supprimer un plugin ne casse rien ». Le cœur définit donc un contrat neutre (le drapeau) ; le plugin se contente de le poser. Plugin retiré, le drapeau n'est jamais posé, le firewall reste inerte : aucune régression.
L'ordre de déclaration fait le reste. Sur un domaine de l'application, le drapeau est absent, le firewall public_site ne matche pas, et les firewalls admin/user s'appliquent exactement comme avant. La liste complète des firewalls est détaillée dans la Référence security.yaml.
L'état passif du domaine¶
Un domaine mappé porte un état de cycle de vie léger : il naît en attente (il a été rattaché à un site mais aucune requête n'y est encore parvenue), puis passe actif dès la première visite. Cette transition est passive : c'est le fait d'être visité qui l'active, sans action explicite de l'utilisateur ni de tâche de fond.
Concrètement, la première requête sur un domaine mappé horodate sa première résolution, fait basculer son état en actif, et estampille sa dernière visite. C'est ce qui permet de savoir, côté exploitation, qu'un domaine branché par un utilisateur a effectivement commencé à recevoir du trafic.
Ces écritures se produisent sur le chemin de lecture — chaque affichage de page. Les persister à chaque requête reviendrait à écrire en base à chaque GET, ce qui est à proscrire, particulièrement en worker mode. Elles sont donc throttlées : la transition d'état s'écrit une fois (elle n'arrive qu'une fois), et l'horodatage de dernière visite n'est réécrit qu'au plus une fois par heure et par domaine. Une seconde visite rapprochée sur un domaine déjà actif ne déclenche aucune écriture.
La variable KIREXO_RESERVED_DOMAINS¶
La liste des domaines réservés à l'application — ceux qui doivent conserver le routage app_* normal et ne jamais être servis comme site public — est fournie par la variable d'environnement KIREXO_RESERVED_DOMAINS (liste de domaines séparés par des virgules).
En développement, elle contient localhost, 127.0.0.1 et l'URL applicative servie par le proxy hôte — app.main.localhost pour le dépôt principal, app.<worktree>.localhost dans un worktree. En production, elle contient l'apex de Kirexo et le sous-domaine d'administration. Elle ne doit pas contenir de domaine de site utilisateur : ceux-là sont résolus dynamiquement en base, jamais listés dans la configuration.
La comparaison porte sur une égalité exacte après normalisation (SiteResolver::isAppDomain(), src/Plugin/Web/src/Service/SiteResolver.php), jamais sur un suffixe. Une URL applicative renommée sans mettre cette liste à jour n'est donc pas dégradée : elle bascule intégralement du côté « domaine de site », ne trouve aucun Site et rend 404 sur toute l'application.
Portée de cette page
Cette page explique le pourquoi de la résolution multi-tenant. La procédure complète pour brancher un domaine côté utilisateur (préparation DNS, *.localhost en développement, obtention du certificat TLS à la demande) sera consolidée dans un guide dédié. La variable KIREXO_RESERVED_DOMAINS est également recensée dans la Référence des variables d'environnement.
Pourquoi TRUSTED_HOSTS n'est pas le filtre des Host en production¶
Symfony propose un filtre natif des en-têtes Host : framework.trusted_hosts, alimenté ici par la variable TRUSTED_HOSTS. Un Host hors de la regex est rejeté en 400 avant tout routage. C'est la parade habituelle contre l'empoisonnement de Host (host header poisoning) : un attaquant forge l'en-tête pour que l'application génère un lien absolu vers son propre domaine, par exemple dans un e-mail de réinitialisation du mot de passe.
Kirexo ne l'utilise pas en production, et ce n'est pas un oubli. Le multi-tenant sert des sites sur des domaines arbitraires, ajoutés en base au fil de l'eau. Une regex écrite à l'installation ne peut pas les connaître : limitée au domaine applicatif, elle rejetterait tous les domaines de site en 400, avant même que la résolution Host → Site ait pu les reconnaître. La variante qui dérive la regex de SERVER_NAME (^<SERVER_NAME>$) ajoute deux défauts : elle ne vaut plus rien dès que SERVER_NAME contient une liste (^a, b$ n'est pas une alternance), et elle ne couvre pas l'hôte interne php sur lequel Caddy appelle l'endpoint ask de l'on-demand TLS. TRUSTED_HOSTS est donc laissé vide, et Symfony ne pose aucun filtre.
Le risque que ce filtre couvre n'est pas laissé ouvert pour autant. Trois protections, déjà présentes dans le code, prennent le relais.
P1 — un Host inconnu reçoit un 404 avant tout rendu¶
HostResolutionSubscriber s'exécute avant le routeur. Un domaine qui n'est ni réservé (SiteResolver::isAppDomain(), égalité exacte) ni mappé à un site (findSiteDomain() rend null) lève une NotFoundHttpException : aucun controller applicatif (connexion, réinitialisation du mot de passe, invitation) n'est joignable sur un Host forgé. Deux chemins seulement échappent à la résolution :
/.well-known/kirexo/on-demand-tls, laissé au routage applicatif. Sa route (src/Plugin/Web/src/Controller/WebPluginTlsAskController.php) est verrouillée enhost: 'php': tout autre hôte obtient un 404 du routeur ;/_wdtet/_profiler, uniquement quandkernel.debugest vrai, donc jamais en production.
Ce que P1 laisse passer est ce que trusted_hosts aurait dû laisser passer : les domaines réservés et les domaines mappés. Tout le reste s'arrête là.
P2 — les liens générés hors HTTP ne lisent jamais un Host¶
Le lien de réinitialisation du mot de passe n'est pas calculé dans la requête qui le demande. Le Mailer place le message dans la file async, et c'est le worker Messenger qui rend le gabarit templates/reset_password/email.html.twig, dont le url() s'évalue sans aucune requête HTTP. Le contexte de routage vient alors de framework.router.default_uri, alimenté par DEFAULT_URI (config/packages/routing.yaml). Un Host forgé ne peut pas atteindre ce calcul : il n'existe tout simplement pas dans le worker.
C'est aussi pourquoi DEFAULT_URI est obligatoire en production. Laissée à la valeur de développement (https://localhost), elle rend le lien inutilisable, et peut laisser l'installateur définitivement enfermé hors de son instance, faute de pouvoir réinitialiser son mot de passe.
P3 — les liens générés en HTTP reprennent un domaine déjà validé¶
D'autres liens absolus sont calculés pendant la requête. C'est le cas de l'URL d'acceptation d'une invitation (InvitationManager::buildEmail(), src/Service/User/InvitationManager.php). Le RouterListener construit alors son contexte à partir de Request::getHost(), le même appel que celui que P1 vient de juger. Le Host qui atteint un controller applicatif est donc forcément un domaine réservé, et celui qui atteint un controller de site un domaine mappé. Pas d'empoisonnement possible tant que P1 tient, à une condition qui relève de l'exploitant : KIREXO_RESERVED_DOMAINS ne doit lister que des domaines qu'il contrôle.
L'invariant qui lie P1 et P2¶
Les deux protections se croisent sur un point : l'hôte de DEFAULT_URI doit figurer dans KIREXO_RESERVED_DOMAINS. Sinon, le lien produit par P2 pointe vers un domaine que P1 ne reconnaît pas comme applicatif, et l'utilisateur qui clique sur le lien de réinitialisation tombe sur un 404.
Et si un exploitant définit quand même TRUSTED_HOSTS ?¶
C'est possible, en défense supplémentaire. La regex devient alors une liste à tenir à jour : elle doit couvrir le domaine applicatif, l'hôte php si l'on-demand TLS est actif, et chaque domaine de site mappé. Un domaine ajouté par un utilisateur sans mise à jour de la regex répond 400, sans que rien dans l'application ne l'explique. La forme attendue est dans la Référence des variables d'environnement.
Voir aussi¶
- Pages spéciales du plugin web — ce qu'un site sert réellement sur son domaine, et le même invariant « admin ≠ publication ».
- Architecture des firewalls Kirexo — la séparation admin/user et le choix du 404 plutôt que du 403, prolongés ici par le firewall d'isolation du site public.
- Architecture — le socle à plugins isolés et le worker mode FrankenPHP qui motivent le routage sans sous-requête.