Mets une porte devant tout un site à ton proxy inverse

La façon normale d'utiliser Caputchin, c'est d'incruster le widget sur une page et de vérifier le token depuis ton backend. Ça demande un endroit où poser le widget et un backend pour vérifier le token. La porte de page au proxy n'a besoin ni de l'un ni de l'autre. Elle place une vérification pleine page devant tout un site ou une route à ton proxy inverse : un visiteur passe une vérification, gagne un laissez-passer éphémère, et se promène sur le site jusqu'à ce que le laissez-passer expire. La vérification est un court jeu ou une confirmation en un geste, selon ce que tu choisis. L'app protégée n'est jamais touchée.

Comme rien n'est ajouté à l'app elle-même, c'est le moyen de protéger des hôtes où tu ne peux pas incruster un script, un portail de connexion mono-page compilé, un appliance, ou un outil interne qui vit derrière un proxy d'authentification.

À qui elle s'adresse

Tourne-toi vers la porte quand le widget en ligne ne convient pas :

L'app n'a pas de place pour le widget. Un portail de connexion scellé (comme Authelia), un appliance de fournisseur, ou toute UI que tu ne peux pas éditer.
Tu veux mettre une porte à toute une surface, pas à un formulaire. "Prouve que tu es humain avant d'atteindre ce site" plutôt qu'un contrôle sur un seul envoi.
Tu n'as pas de backend pour vérifier un token. Le proxy fait respecter la règle ; il n'y a pas d'appel /siteverify à écrire.

Pour une page ou un formulaire normal que tu contrôles, incruste plutôt le widget, il est plus léger et ne redirige pas le visiteur. Si tu as un formulaire mais pas de backend, la vérification hébergée convient mieux.

Comment ça marche

Une seule résolution achète beaucoup de requêtes. Le visiteur passe la vérification une fois ; après ça, un cookie propriétaire dégage ses requêtes jusqu'à ce qu'il expire.

Le proxy fait un petit appel à l'autorisateur de Caputchin à chaque requête. Quand la requête ne porte pas de laissez-passer valide, Caputchin répond 401 et le proxy redirige le visiteur vers le défi hébergé. Quand le laissez-passer est présent et valide, Caputchin répond 204 et le proxy laisse passer la requête vers ton app.

Le laissez-passer vit dans un cookie propriétaire, nommé cpt_gate par défaut et renommable par clé de site, posé sur ton propre domaine par un petit callback que tu héberges (à /__cpt/callback par défaut, déplaçable aussi). C'est un token signé et éphémère, non lié à un appareil, donc sa sûreté vient entièrement des attributs du cookie (HttpOnly, Secure, SameSite=Lax) et d'une courte TTL que tu choisis. Comme il pose un cookie chez tes visiteurs, mentionne-le dans ta politique de cookies. Le guide de configuration parcourt le callback et les attributs requis.

Ce qui est laissé de côté intentionnellement

Pas de porte auto-hébergée. Caputchin héberge le défi et vérifie le laissez-passer ; tu ne fais pas tourner de vérificateur. Ton proxy transmet seulement un cookie et suit les redirections.
Un contrôle par requête, pas une validation locale du token. Le proxy demande à Caputchin à chaque requête. Le mode d'échec que tu choisis (ouvert ou fermé) décide de ce qui arrive si Caputchin est brièvement injoignable.
Un laissez-passer par clé de site, à portée de cookie. Un laissez-passer dégage une origine, pas un compte entier ni plusieurs domaines, parce que c'est un cookie propriétaire ordinaire.
Pas de texte sur mesure. Tu choisis la langue et le thème de la page de vérification, pas sa formulation.
Ni session ni connexion. La porte prouve qu'un humain a atteint le site ; ton app gère toujours l'authentification et ses propres limites de débit. Les deux se cumulent.

Ce que voit le visiteur

La page de vérification parle la langue du visiteur et suit sa préférence clair ou sombre, et elle porte la même marque que le widget de cette clé de site, parce qu'elle résout les deux depuis la même clé de site que tu as déjà configurée. Tu peux plutôt figer une langue ou un thème, et choisir entre un jeu et une case à cocher en un geste, sur la page Porte de proxy de la clé de site. Vois Personnalise le défi.

Voir aussi

Configurer la porte de page au proxy : active-la et câble ton proxy de bout en bout.
Personnalise le défi : jeu ou case à cocher, langue, thème, nom du cookie, chemin du callback.
Recettes de proxy inverse : nginx, Traefik, Caddy, et l'exemple travaillé d'Authelia.
Statistiques de la porte de page au proxy : lis le ratio de passage direct sur défi.
Vérification hébergée : l'option sans backend quand tu as bien un formulaire à nous pointer.