Fichiers /.well-known d'une application
Fichiers /.well-known d'une application
Une application installée peut publier des fichiers statiques sous l'adresse /.well-known/ du site. C'est utile pour une vérification de domaine : un service externe demande un fichier à une adresse fixe pour s'assurer que vous contrôlez le site.
Prérequis
- Une application installée sur le site.
- Un accès au code de l'application.
Publier un fichier
- Dans le dossier du module Python de l'application (celui qui contient
hooks.py), créez le dossierwww/.well-known/. - Placez-y le fichier. Vous pouvez créer des sous-dossiers.
- Mettez à jour le code de l'application sur le serveur, puis demandez l'adresse
/.well-known/<chemin du fichier>enGET.
Le fichier est lu sur le disque à chaque requête. Aucun cache ne le conserve. Une mise à jour du code suffit : un redémarrage, une migration ou un vidage du cache ne sont pas nécessaires. De même, un fichier modifié ou supprimé est pris en compte dès la requête suivante.
L'application doit être installée sur le site (bench --site <site> install-app <app>). Le fichier d'une application présente sur le serveur mais pas installée sur le site n'est pas servi.
Le chemin demandé après /.well-known/ est cherché dans le dossier www/.well-known/ de chaque application installée. Dodock sert le premier fichier trouvé, puis s'arrête. Si deux applications publient le même chemin, seul le fichier de la première application qui le contient est servi.
Réponse du serveur
| Situation | Réponse |
|---|---|
| Le fichier existe | Son contenu, avec le type de contenu déduit de l'extension (.json donne application/json) |
| Le fichier n'a pas d'extension reconnue | Son contenu, avec le type text/plain |
| Le chemin n'existe dans aucune application, ou désigne un dossier | Erreur 404 |
Le chemin sort du dossier www/.well-known/ (par exemple /.well-known/../hooks.py) | Erreur 404 |
Adresses déjà prises en charge par Dodock
Ces adresses sont traitées avant la recherche d'un fichier d'application :
/.well-known/security.txt: contenu du document Paramètres de sécurité, servi uniquement en HTTPS./.well-known/openid-configuration: configuration OpenID du site (voir OAuth)./.well-known/oauth-authorization-serveret/.well-known/oauth-protected-resource: métadonnées OAuth, tant qu'elles sont activées sur le site.
Si les métadonnées OAuth ne sont pas activées, un fichier d'application peut occuper ces deux dernières adresses.
Exemple
Exemple fictif. Un service tiers demande un fichier de vérification de domaine nommé openai-apps-challenge. Votre application s'appelle mon_app.
- Créez le fichier
mon_app/www/.well-known/openai-apps-challenge(dans le dossier du modulemon_app) avec pour seul contenujeton-exemple-123. - Mettez à jour le code de l'application sur le serveur. Aucun redémarrage n'est nécessaire.
- Ouvrez
https://votre-site.example.com/.well-known/openai-apps-challenge.
Le navigateur affiche jeton-exemple-123 avec le type text/plain. Un fichier mon_app/www/.well-known/mcp/server-card.json serait servi à l'adresse /.well-known/mcp/server-card.json avec le type application/json.
Limites
- Seules les requêtes
GETsont traitées. - Les fichiers sont publics : n'y placez aucun secret.
- Avec la configuration nginx générée par bench, les adresses
/.well-known/acme-challenge/sont réservées aux certificats Let's Encrypt. Un fichier d'application placé à ce chemin n'est pas servi.