--- type: explanation title: Mets une porte devant tout un site à ton proxy inverse summary: Ce qu'est la porte de proxy, à qui elle s'adresse, et comment un visiteur résout un jeu pour gagner un laissez-passer éphémère qui dégage ses requêtes, pour que tu protèges des apps où tu ne peux pas incruster le widget. --- La façon normale d'utiliser Caputchin, c'est d'incruster le [widget](/docs/site-keys/embedding-the-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 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 résout un jeu, gagne un laissez-passer éphémère, et se promène sur le site jusqu'à ce que le laissez-passer expire. 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. La porte de proxy existe à partir du plan Alpha, activée par clé de site. Caputchin héberge le défi et émet le laissez-passer ; tu pointes ton proxy inverse existant (nginx, Traefik, Caddy, ou quoi que ce soit qui fait face à ton app) vers elle. ## À 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](/docs/site-keys/embedding-the-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](/docs/hosted-verification/overview) convient mieux. ## Comment ça marche Une seule résolution achète beaucoup de requêtes. Le visiteur joue le jeu une fois ; après ça, un cookie propriétaire dégage ses requêtes jusqu'à ce qu'il expire. ```mermaid sequenceDiagram participant V as Visiteur participant P as Ton proxy inverse participant C as Caputchin V->>P: demande une URL protégée P->>C: contrôle authz (transmet le cookie cpt_gate) C-->>P: 401, pas encore de laissez-passer valide P-->>V: 302 vers le défi hébergé V->>C: joue le jeu C-->>V: laissez-passer, auto-POST vers ton callback V->>P: POST le laissez-passer vers /__cpt/callback P-->>V: pose le cookie cpt_gate, redirige en arrière V->>P: demande de nouveau (cookie présent) P->>C: contrôle authz C-->>P: 204 autoriser P-->>V: ton app répond ``` 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 cookie de laissez-passer Le laissez-passer vit dans un cookie propriétaire nommé `cpt_gate`, posé sur ton propre domaine par un petit callback que tu héberges. 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](/docs/proxy-page-gate/set-up) 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. - **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. ## Voir aussi - [Configurer la porte de proxy](/docs/proxy-page-gate/set-up) : active-la et câble ton proxy de bout en bout. - [Recettes de proxy inverse](/docs/proxy-page-gate/reverse-proxy-recipes) : nginx, Traefik, Caddy, et l'exemple travaillé d'Authelia. - [Statistiques de la porte de proxy](/docs/proxy-page-gate/statistics) : lis le ratio de passage direct sur défi. - [Vérification hébergée](/docs/hosted-verification/overview) : l'option sans backend quand tu as bien un formulaire à nous pointer.