Sécurité et HTTPS¶

Cette page rassemble les paramètres de sécurité de l’instance : HTTPS et certificats, protection contre les bots (Anubis) et les variables les plus sensibles du fichier .env.

Elle s’adresse à la personne qui administre l’instance (SuperAdmin ou profil plus technique/opérationnel).

HTTPS et certificats¶

Farinha fonctionne derrière Caddy, qui gère le HTTPS automatiquement :

Avec une adresse publique configurée (par exemple, farinha.votreInstitution.org) : Caddy obtient et renouvelle automatiquement des certificats gratuits.
Avec vos propres certificats : placez les fichiers fullchain.pem et privkey.pem dans le dossier certs/, à la racine du projet. Ils ont la priorité sur les certificats automatiques.
Sans adresse publique et sans certificats propres (par exemple, localhost ou une IP) : la sécurité est désactivée, car les certificats automatiques exigeraient l’installation d’une autorité de certification sur les clients. Dans ce cas, il est important de configurer une adresse publique ou vos propres certificats dès que possible.

Si, pour une raison quelconque, vous souhaitez désactiver le HTTPS malgré tout, définissez dans le .env :

DISABLE_HTTPS=True

Farinha derrière un autre proxy inverse¶

Il est courant que l’institution place Farinha derrière une autre couche de proxy inverse (par exemple, un proxy en périphérie, un répartiteur de charge, un CDN ou un panneau de proxy comme Nginx Proxy Manager). La topologie se présente ainsi :

Proxy/CDN externe
    ↓
Proxy inverse intermédiaire
    ↓
Caddy (conteneur Farinha)
    ↓
Gunicorn/Django

Dans ce scénario, il est fréquent que le proxy intermédiaire ne transmette pas à Caddy les informations nécessaires pour terminer la validation automatique du certificat (par exemple, le domaine dans la poignée de main TLS, aussi appelé SNI). Sans pouvoir obtenir le certificat public, Caddy présente un certificat interne, émis par sa propre autorité locale :

Issuer: Caddy Local Authority - ECC Intermediate
Subject Alternative Name: farinha.exemplo.org

Ce certificat est valide pour Caddy, mais il n’est pas reconnu par les proxys en amont ni par les navigateurs. Le résultat est généralement l’un de ces symptômes :

erreur de certificat invalide sur le proxy/CDN externe (par exemple, 526 Invalid SSL Certificate sur Cloudflare en mode strict) ;
502 Bad Gateway sur le proxy intermédiaire, car il ne parvient pas à terminer la connexion HTTPS sécurisée avec Caddy ;
boucle de redirection : le proxy transmet vers le port 80, Caddy répond 308 Permanent Redirect vers HTTPS, et le navigateur alterne entre les deux.

Le problème est le même avec n’importe quel proxy ; la cause est généralement l’une de ces deux choses :

le proxy n’envoie pas le domaine dans la poignée de main TLS (SNI), donc Caddy ne sélectionne pas le bon certificat ;
le proxy essaie de valider le certificat de Caddy et le rejette, car il s’agit du certificat interne.

Solution pratique (exemple avec Nginx Proxy Manager) :

Dans le Proxy Host du domaine, sous Details, pointez vers Farinha en HTTPS sur le port de Caddy :
Scheme : https
Forward Hostname/IP : IP du conteneur Farinha (ex. : 10.0.0.14)
Forward Port : 443

Cela évite la boucle, car le proxy ne passe plus par le port 80 (qui redirige toujours vers HTTPS).

Dans l’onglet SSL, conservez le certificat du domaine et Force SSL activé.
Dans l’onglet Advanced, envoyez le domaine dans la poignée de main et acceptez le certificat interne de l’amont :

proxy_ssl_server_name on;
proxy_ssl_name farinha.exemplo.org;
proxy_ssl_verify off;

proxy_ssl_server_name on; : envoie le SNI dans la poignée de main, ce qui permet à Caddy de sélectionner le certificat correct pour le domaine ;
proxy_ssl_name farinha.exemplo.org; : définit quel domaine est envoyé comme SNI ;
proxy_ssl_verify off; : accepte le certificat interne de Caddy en amont.

Sur d’autres proxys, recherchez les options équivalentes : activer le SNI/conserver le nom d’hôte en amont et désactiver la vérification du certificat en amont.

Attention : désactiver la vérification maintient la connexion chiffrée, mais ne valide pas l’identité du certificat de Caddy. C’est acceptable comme solution provisoire sur un réseau interne/contrôlé.

Une fois l’accès direct fonctionnel, rétablissez le mode le plus strict sur le proxy/CDN externe (par exemple, Full (strict) sur Cloudflare).

Solutions définitives (préférables à verify off) :

Certificat public sur Caddy : configurer FARINHA_URL avec le domaine et le laisser terminer le défi ACME, afin que Caddy présente un certificat de confiance et que la vérification puisse être réactivée.
Certificats propres de confiance : utiliser des certificats d’une autorité reconnue par les proxys (option certs/).
Désactiver le HTTPS sur Farinha avec DISABLE_HTTPS=True et pointer le proxy vers http sur le port 80 du conteneur. Cela fonctionne, mais le segment entre le proxy et Farinha n’est plus chiffré ; évaluez le risque dans votre environnement. Dans ce cas, gardez le HTTPS uniquement en périphérie (proxy/CDN).

Protection contre les bots (Anubis)¶

Farinha peut utiliser Anubis, un pare-feu qui demande aux visiteurs une petite preuve de travail pour bloquer les accès automatisés (bots), réduisant la charge lors des pics de trafic.

La protection est contrôlée par deux paramètres de l’application, dans le panneau interne d’administration (Django Admin) :

Webapp -> Configurations de l'application -> « Anubis habilitado? »
Webapp -> Configurations de l'application -> « Dificuldade do Desafio Anubis » (Muito leve (1), Leve (3), Padrão (4) et Forte (10))

Les configurations de l’application incluent la carte du portail et la protection contre les bots (Anubis).

Points importants :

La modification d’Anubis (activer/désactiver ou difficulté) prend effet après le redémarrage de Farinha. Lors de l’enregistrement, le panneau le signale.
Le run (scripts run.sh/run.bat) lit ces configurations dans la base de données et les applique au démarrage de l’instance.
La difficulté « Padrão (4) » est un bon point de départ. Des valeurs élevées alourdissent le défi et peuvent gêner les utilisateurs ; des valeurs trop faibles réduisent la protection.
Si le défi n’apparaît pas pour les visiteurs, vérifiez que « Anubis habilitado? » est coché et redémarrez Farinha.

Voir aussi : Portail.

Variables sensibles du `.env`¶

Le fichier .env (créé à partir du .env-sample lors de la première exécution) regroupe les configurations de l’instance. Les plus importantes pour la sécurité :

FARINHA_URL : domaine(s) ou IP(s) d’accès, séparés par des virgules (sans https://). Avec un domaine public, le HTTPS est activé automatiquement.
ADMIN_PATH : chemin du panneau interne d’administration. Par défaut : admin/. Voir Utilisateur SuperAdmin.
SECRET_KEY : clé qui protège les données sensibles. Elle est obligatoire : sans elle, Farinha ne démarre pas. Elle est générée automatiquement par run.sh/run.bat ; si vous la créez manuellement, n’utilisez pas le caractère $ (Docker Compose l’interpréterait comme une variable d’environnement).
SECURE_HSTS_SECONDS : HSTS. Gardez 0 (désactivé) jusqu’à être sûr que le HTTPS fonctionne, car le HSTS peut rendre le site inaccessible si les certificats ne sont pas corrects. Activez-le uniquement si vous savez ce que vous faites.
SECURE_HSTS_INCLUDE_SUBDOMAINS : inclut les sous-domaines dans le HSTS.
SECURE_PROXY_SSL_HEADER et SECURE_PROXY_SSL_HEADER_VALUE : indiquent à Django que la requête d’origine est sécurisée lorsqu’un proxy est en amont (déjà configuré par défaut pour Caddy).
SECURE_CONTENT_TYPE_NOSNIFF : empêche les navigateurs de deviner le type de fichier.
DEBUG : en production, gardez False (valeur par défaut du .env-sample).
SQLITE_BUSY_TIMEOUT_MS : temps d’attente de la base de données lorsqu’elle est occupée.

Précautions :

Ne publiez jamais le fichier .env ni la SECRET_KEY (ne les envoyez pas par e-mail, messagerie ou ticket).
Lorsque vous modifiez des variables, arrêtez et redémarrez l’instance (./down.sh && ./run.sh sous Linux ; .\down.bat et .\run.bat sous Windows).

Bonnes pratiques¶

Conservez des permissions restreintes sur le .env ; il contient la SECRET_KEY.
Générez une SECRET_KEY propre et exclusive à chaque instance (le run le fait déjà automatiquement). Ne réutilisez jamais la clé d’une autre installation.
Avant d’activer le HSTS (SECURE_HSTS_SECONDS), confirmez que le HTTPS fonctionne sur tous les domaines et sous-domaines utilisés. Le HSTS est difficile à annuler côté client.
En production, gardez DEBUG=False.
Si vous changez le chemin du panneau avec ADMIN_PATH, partagez la nouvelle adresse avec l’équipe et évitez les chemins évidents comme admin/ ou panneau/.
Faites une sauvegarde de la base de données (db/) et de vos certificats (certs/), si vous en utilisez.
Si vous utilisez un autre proxy inverse devant Farinha, préférez la solution définitive (certificat public ou propre de confiance) plutôt que de laisser la vérification du certificat désactivée en amont trop longtemps.

Problèmes courants¶

Farinha ne démarre pas : vérifiez que la SECRET_KEY existe dans le .env et ne contient pas $. L’erreur apparaît dans les journaux du conteneur.
Avertissement de certificat invalide dans le navigateur : il peut s’agir du certificat interne de Caddy, car le domaine n’est pas correctement configuré dans FARINHA_URL, ou parce que la validation automatique n’a pas pu aboutir. Consultez aussi la sous-section sur le proxy ci-dessus.
Erreur de certificat (526) ou 502 sur le proxy/CDN : voir la sous-section Farinha derrière un autre proxy inverse ; il s’agit généralement de l’amont HTTPS sans SNI et avec la vérification du certificat activée.
Boucle de redirection : le proxy pointe vers le port 80 de Caddy, qui redirige toujours vers HTTPS. Utilisez https sur le port 443 ou désactivez le HTTPS sur Farinha.
Le défi Anubis n’apparaît pas : vérifiez que « Anubis habilitado? » est coché dans les Configurations de l'application et redémarrez Farinha.
J’ai modifié la configuration d’Anubis et rien ne change : les modifications ne prennent effet qu’après le redémarrage de Farinha (l’avertissement s’affiche dans le panneau lors de l’enregistrement).
Le défi Anubis gêne les intégrations internes : envisagez de désactiver la protection ou de réduire la difficulté, en gardant à l’esprit le redémarrage nécessaire.