Sous-domaine, sous-répertoire ou domaine distinct ? Comment choisir une structure d’URL pour une application auto-hébergée
Choisir l’emplacement d’une application auto-hébergée a des conséquences sur la configuration du proxy inverse, les cookies, les rappels d’authentification, les webhooks, TLS, les efforts de migration et les périmètres administratifs. Utilisez ce guide pour sélectionner une structure d’URL et la valider avant le lancement.
Pourquoi la structure d’URL est une décision opérationnelle, et pas seulement une décision de marque
Une URL fait partie du contrat public d’une application. Les utilisateurs l’enregistrent, les navigateurs lui appliquent des règles d’origine et de cookies, les fournisseurs d’identité peuvent l’enregistrer, les émetteurs de webhooks y envoient des requêtes, et les clients API ou les contenus intégrés peuvent la stocker. Modifier l’URL ultérieurement peut donc affecter davantage que les marque-pages et les liens de recherche.
Les trois modèles les plus courants sont un sous-domaine dédié tel que https://app.example.com, un sous-répertoire derrière un site existant tel que https://example.com/app, et un domaine distinct tel que https://exampleapp.com. Le meilleur choix dépend du modèle de déploiement documenté de l’application et de vos exigences opérationnelles, et non simplement de l’adresse qui paraît la plus courte.
Une distinction technique essentielle est l’origine. Une origine web repose sur le schéma, l’hôte et le port ; le chemin ne fait pas partie de l’origine. Par conséquent, https://example.com/app partage une origine avec les autres contenus de https://example.com, tandis que https://app.example.com utilise un hôte différent et donc une origine différente. Cette différence peut avoir de l’importance pour le comportement des navigateurs, la conception des intégrations et les attentes en matière d’isolation.
- Choisissez l’URL publique avant d’inviter des utilisateurs, de connecter un fournisseur d’identité ou de publier des points de terminaison de webhook.
- Traitez l’URL canonique de l’application comme une configuration à documenter et à maintenir.
- Ne supposez pas qu’un proxy inverse peut faire fonctionner correctement n’importe quelle application sous un préfixe de chemin.
Les trois modèles en un coup d’œil
Un sous-domaine dédié place l’application à une adresse telle que https://crm.example.com. Pour de nombreuses applications auto-hébergées, il s’agit de la configuration publique la plus simple, car l’application peut généralement considérer / comme son chemin de base. Le proxy inverse effectue le routage selon le nom d’hôte, et les liens générés, les ressources statiques et les redirections n’ont pas besoin d’inclure un préfixe de chemin public supplémentaire.
Un sous-répertoire place l’application sous un nom d’hôte existant, par exemple https://example.com/analytics. Cela peut créer un site public unifié et être utile lorsqu’une entreprise doit présenter un seul nom d’hôte. Toutefois, cela impose que le proxy inverse et l’application comprennent correctement le chemin de base /analytics.
Un domaine distinct place l’application sur un nom séparé, tel que https://example-portal.com. Cette option peut clarifier les frontières entre produits, clients, unités opérationnelles ou exigences de gouvernance. Elle crée également une surface distincte de DNS, TLS, propriété de domaine et cycle de vie à gérer.
- Sous-domaine dédié : généralement l’option par défaut la moins complexe pour une application dotée de sa propre connexion et de ses intégrations.
- Sous-répertoire : approprié uniquement après confirmation, dans la documentation officielle de l’application et dans un environnement de préproduction, de la prise en charge des URL relatives.
- Domaine distinct : utile lorsqu’une frontière publique, administrative ou organisationnelle claire est plus importante que le maintien de l’application sous le domaine principal de la marque.
Commencez par l’application : vérifiez la prise en charge documentée de l’URL de base et du proxy inverse
Commencez par la documentation d’installation et de proxy inverse de l’application elle-même. Recherchez spécifiquement les paramètres pris en charge nommés base URL, external URL, site URL, root URL, relative URL, webroot, public URL, trusted proxy, forwarded headers, ou un terme similaire. La terminologie varie selon le produit, et la prise en charge est propre à chaque produit.
Un proxy peut supprimer un préfixe public avant de transmettre une requête. Par exemple, un proxy peut accepter /app et transmettre la requête à un backend qui écoute sur /. Le middleware StripPrefix de Traefik effectue ce type de suppression de préfixe et fournit le préfixe retiré dans X-Forwarded-Prefix. Mais supprimer un chemin au niveau du proxy ne rend pas automatiquement l’application consciente que son adresse publique inclut ce chemin.
L’application doit toujours générer les liens publics, les URL de ressources, les redirections, les cibles de formulaires et les URL de rappel avec le bon préfixe. La documentation officielle peut aussi révéler des limites. GitLab, par exemple, documente l’installation avec URL relative comme une alternative, mais recommande en temps normal son propre domaine ou sous-domaine et décrit des limitations. C’est un rappel utile de ne pas généraliser le comportement d’un produit à un autre.
- Lisez la documentation de déploiement de l’éditeur avant de sélectionner un sous-répertoire.
- Confirmez que l’application prend en charge une URL relative ou un webroot, et pas seulement un proxy inverse générique.
- Identifiez les en-têtes de proxy requis et les paramètres de proxy approuvé.
- Consignez l’URL externe canonique exacte dans la documentation de déploiement.
- Effectuez un test de préproduction avec l’URL publique prévue, et non seulement avec une adresse directe de conteneur ou interne.
Authentification et intégrations : URL de rappel, liens d’e-mail, contenu intégré et webhooks
L’authentification rend souvent une migration d’URL visible. Les intégrations OAuth peuvent exiger l’enregistrement des points de terminaison de redirection auprès du serveur d’autorisation. Lorsqu’une URI de redirection complète est enregistrée, OAuth 2.0 exige une comparaison par chaîne simple de l’URI demandée. Un passage de https://example.com/app/callback à https://app.example.com/callback peut donc nécessiter une modification de configuration chez le fournisseur d’identité, même si l’application elle-même fonctionne.
Inventoriez chaque service externe qui stocke ou affiche l’URL publique. Cela inclut couramment les paramètres d’authentification unique, les e-mails de réinitialisation de mot de passe et d’invitation, les pages intégrées externes, la configuration des clients API, les clients mobiles ou de bureau, ainsi que les émetteurs de webhooks. Une ancienne valeur peut ne pas être détectée avant qu’un utilisateur suive un flux d’e-mail rarement utilisé ou qu’une intégration en arrière-plan tente une livraison.
Les webhooks méritent une étape de validation distincte, car leur émetteur est un client HTTP externe. L’URL de charge utile configurée doit être mise à jour lorsque nécessaire, et la livraison doit être testée une fois la nouvelle adresse active. Pour les services qui valident les certificats TLS, vérifiez que le point de terminaison présente le certificat valide attendu et qu’il est accessible publiquement sur la route requise.
- Listez chaque URI de redirection OAuth ou SSO avant le lancement ou la migration.
- Envoyez de véritables invitations de test, réinitialisations de mot de passe et e-mails de notification vers une boîte aux lettres contrôlée.
- Testez le contenu intégré depuis le site ou le produit qui l’hébergera réellement.
- Inventoriez les émetteurs de webhooks entrants, mettez à jour la configuration de leurs points de terminaison et déclenchez une livraison de test.
- Vérifiez les clients API et les outils d’automatisation pour détecter les URL de base codées en dur.
DNS, certificats TLS et routage pour chaque modèle
Le choix d’un nom d’hôte crée du travail lié au DNS et aux certificats. Les autorités de certification valident le contrôle des noms de domaine inclus dans un certificat ; le nom d’hôte sélectionné doit donc se résoudre et être routé d’une manière compatible avec la méthode de validation retenue. La validation HTTP-01 de Let’s Encrypt récupère un défi sous /.well-known/acme-challenge/ sur le port 80. Le DNS et le routage public font donc partie de la préparation au lancement de l’application, et ne sont pas une tâche à reporter après la configuration de l’application.
Un sous-domaine nécessite normalement un enregistrement DNS pour ce nom d’hôte et un certificat qui le couvre. Un domaine distinct requiert le même travail pour un autre nom de domaine. Un sous-répertoire n’ajoute pas de nom d’hôte, mais il exige des règles précises de routage par chemin et une coexistence avec les routes, les redirections et la gestion des défis du site principal.
Les certificats génériques constituent un choix de conception distinct. Let’s Encrypt indique que HTTP-01 ne peut pas émettre de certificats génériques ; leur émission nécessite une validation DNS-01. Ne choisissez pas une approche de certificat générique uniquement pour éviter de planifier des noms d’hôte individuels, sauf si vous pouvez exploiter de manière sûre le processus de validation DNS requis.
- Confirmez la propriété DNS et identifiez qui peut modifier les enregistrements concernés.
- Vérifiez que le nom d’hôte prévu se résout avant l’émission du certificat et le lancement public.
- Vérifiez que le port 80 et la route de défi ACME sont accessibles lors de l’utilisation de la validation HTTP-01.
- Définissez la priorité de routage afin que le site principal, les routes de l’application et les chemins de défi n’entrent pas en conflit.
- Lorsque Docker est utilisé, n’exposez que les ports nécessitant un accès externe ; un proxy inverse peut atteindre les services via le réseau hôte ou Docker sans publier publiquement tous les ports des conteneurs.
Données et gouvernance : décidez à qui appartient la frontière
La structure de domaine doit refléter la responsabilité opérationnelle autant que l’expérience utilisateur. Demandez-vous qui contrôle l’enregistrement du domaine, les enregistrements DNS, les modifications liées aux certificats, l’administration de l’application, les contacts de facturation et l’accès d’urgence. Une URL techniquement pratique peut devenir un risque opérationnel si elle dépend d’un compte personnel ou de l’accès DNS d’une équipe sans rapport.
Un domaine distinct peut être utile lorsqu’un client, une entreprise acquise, une unité réglementée ou un produit autonome nécessite une frontière publique et administrative plus claire. Un sous-domaine dédié peut fournir une frontière pratique au sein d’un domaine parent géré de manière centralisée. Un sous-répertoire est souvent à réserver aux cas où un nom d’hôte partagé est réellement requis et où la prise en charge de l’application a été vérifiée.
Aucun de ces choix ne résout automatiquement la gouvernance des accès. Définissez qui administre l’application, qui détient l’accès DNS, qui approuve les changements d’intégration, où la gouvernance des sauvegardes est assurée et comment les accès sont transférés en cas de changement de personnel ou de fournisseur.
- Documentez le propriétaire légal et opérationnel de chaque domaine et zone DNS.
- Évitez qu’une seule personne contrôle l’accès au registraire, au DNS et à l’administrateur de l’application.
- Attribuez des responsables pour les paramètres du fournisseur d’identité, les configurations de webhooks et les procédures de récupération.
- Utilisez un domaine distinct lorsqu’un cycle de vie ou une frontière de propriété indépendante est une exigence prioritaire.
Planifiez la migration : les redirections aident, mais ne mettent pas à jour toutes les dépendances
Un sous-domaine est souvent plus facile à modifier qu’un déploiement en sous-répertoire, car l’application peut généralement rester enracinée sur /. Cela ne signifie pas que les changements de nom d’hôte sont sans conséquences. Le nouveau nom d’hôte modifie l’origine du navigateur, peut nécessiter un nouveau certificat et un nouvel enregistrement DNS, et peut exiger des mises à jour des rappels enregistrés, des destinations de webhook, des clients API, des modèles d’e-mail et des listes d’autorisation.
Un passage d’un sous-répertoire à un sous-domaine peut simplifier la future configuration du proxy, mais il modifie tout de même l’URL canonique. Les instructions de migration documentées par GitLab en offrent un exemple concret utile : changer l’URL modifie les URL de dépôts distants, que les utilisateurs peuvent devoir mettre à jour manuellement. Les redirections peuvent préserver les anciens liens accessibles dans le navigateur, mais elles ne réécrivent pas la configuration distante détenue par chaque utilisateur ou système tiers.
Testez les redirections selon les types de requêtes réellement reçus par votre application. Les redirections HTTP relèvent du comportement du client, et ne garantissent pas que tous les clients réagissent de la même manière. La sémantique HTTP distingue également le comportement des méthodes : 301 et 302 peuvent entraîner la transformation d’un POST en GET, tandis que 307 et 308 préservent la méthode. Ne supposez pas qu’une redirection testée dans un navigateur prouve qu’un client API ou un émetteur de webhook se comportera correctement.
- Créez un inventaire des anciennes URL avant de modifier l’adresse canonique.
- Mettez à jour la configuration de l’application, les fournisseurs d’identité, les émetteurs de webhooks, les clients API, la documentation et les communications destinées aux utilisateurs.
- Conservez un plan de redirection délibéré pour le trafic des navigateurs, comprenant une date de retrait et une approche de surveillance.
- Testez les flux de travail basés sur POST et les clients externes séparément de la navigation GET ordinaire.
- Indiquez aux utilisateurs lorsqu’ils doivent mettre à jour manuellement les dépôts distants enregistrés, les marque-pages, les paramètres clients ou les listes d’autorisation.
Questions fréquentes
Un sous-domaine ou un sous-répertoire est-il préférable pour une application auto-hébergée ?
Un sous-domaine dédié est généralement l’option par défaut la plus simple, car l’application peut fonctionner depuis /. Choisissez un sous-répertoire uniquement si vous avez besoin d’un nom d’hôte partagé et que la documentation officielle de l’application, ainsi qu’un test de préproduction, confirment une prise en charge fiable des URL relatives ou du webroot.
Un proxy inverse peut-il faire fonctionner n’importe quelle application dans un sous-répertoire ?
Non. Un proxy inverse peut supprimer un préfixe de chemin public avant de transmettre les requêtes, mais l’application doit toujours générer ses ressources, redirections, liens et intégrations à l’aide du préfixe public. Le routage du proxy seul n’apporte pas la prise en charge de l’URL de base au niveau de l’application.
Les cookies rendent-ils les sous-répertoires non sûrs ?
L’attribut Path d’un cookie limite les situations dans lesquelles un navigateur envoie ce cookie, mais il ne constitue pas une frontière de sécurité. Les applications sous un même nom d’hôte nécessitent une configuration délibérée des cookies et ne doivent pas s’appuyer sur la séparation par chemin comme protection entre services administrés indépendamment.
Que faut-il modifier lorsqu’une application est déplacée vers un nouveau nom d’hôte ?
Examinez l’URL canonique de l’application, le DNS, le certificat TLS, les URI de redirection OAuth ou SSO, les liens de réinitialisation de mot de passe et d’invitation, les URL de charge utile de webhook, les clients API, le contenu intégré, la documentation, les listes d’autorisation et les clients configurés par les utilisateurs. Les redirections peuvent aider pour les liens de navigateur, mais elles ne mettent pas automatiquement à jour les configurations externes.
Comment Airbip peut-il aider avec le routage d’URL pour un déploiement d’application géré ?
Airbip déploie les applications du catalogue sous forme de charges de travail Docker sur des serveurs cloud Airbip et automatise le routage ainsi que les certificats TLS via Traefik et Let’s Encrypt. Il inclut également des vérifications DNS, la gestion du cycle de vie des services et des sauvegardes quotidiennes, hebdomadaires et mensuelles configurables. Les clients peuvent utiliser un sous-domaine Airbip ou un domaine personnalisé compatible. Le client doit toujours choisir l’URL appropriée pour l’application, vérifier la prise en charge de l’URL de base au niveau de l’application, configurer l’identité et les intégrations, et prendre les décisions pertinentes en matière de données, d’accès et de gouvernance.
Sources et lectures complémentaires
- Traefik StripPrefix middleware documentation — Traefik Labs
- GitLab: Install under a relative URL — GitLab
- GitLab: Migrate from a relative URL to a subdomain — GitLab
- Nextcloud Server Administration Manual — Nextcloud GmbH
- RFC 6265: HTTP State Management Mechanism — IETF
- RFC 6749: The OAuth 2.0 Authorization Framework — IETF
- RFC 6454: The Web Origin Concept — IETF
- RFC 9110: HTTP Semantics — IETF
- Challenge Types — Let’s Encrypt / Internet Security Research Group
- Docker networking overview — Docker
Comment les déploiements en sous-répertoire affectent les chemins, les redirections, les cookies et les liens générés
Le routage en sous-répertoire échoue de manière particulièrement visible lorsqu’une application génère des liens relatifs à la racine tels que /assets/app.css ou /login au lieu de /app/assets/app.css et /app/login. Le navigateur demande l’adresse relative à la racine, et le proxy peut la router vers le site principal ou renvoyer une erreur. Une page peut ainsi paraître partiellement fonctionnelle alors que ses feuilles de style, son JavaScript, ses images, ses appels API ou son flux de connexion échouent.
La gestion des redirections requiert la même attention. Une connexion, déconnexion, confirmation de réinitialisation de mot de passe, un téléchargement de fichier ou une redirection de canonicalisation réussis doivent renvoyer les utilisateurs vers l’adresse publique préfixée. Testez à la fois la navigation habituelle dans le navigateur et les actions qui amènent le serveur à émettre des redirections.
Les cookies doivent être examinés délibérément lorsque plusieurs services partagent un nom d’hôte. Un cookie avec un attribut Domain pour un domaine parent peut être envoyé aux sous-domaines correspondants. L’attribut Path d’un cookie contrôle les chemins de requête qui reçoivent un cookie, mais il ne constitue pas une frontière de sécurité entre les applications partageant un nom d’hôte. Évitez de considérer la séparation par chemin comme équivalente à un hôte distinct ou à un domaine géré séparément.