---
type: tutorial
title: Configurer la porte de proxy avec nginx
summary: Active la porte sur une clé de site, câble un proxy inverse nginx de bout en bout, et observe-la en mode aperçu avant qu'elle ne bloque un seul vrai visiteur.
---

À la fin de ce tutoriel, la porte tournera devant un site derrière nginx : un visiteur non dégagé est envoyé à un jeu, un jeu résolu pose un cookie, et les requêtes suivantes passent tout droit. Tu observeras tout le processus d'abord en **mode aperçu**, pour que rien ne soit bloqué tant que tu n'as pas confirmé le câblage. Ici on utilise nginx ; les [recettes Traefik, Caddy et Authelia](/docs/proxy-page-gate/reverse-proxy-recipes) suivent la même forme.

<Callout type="tip">
Fais l'étape 1 avant de toucher ton proxy. Le mode aperçu laisse la porte tourner en surveillance seule : le tableau de bord note ce qu'elle *aurait* fait, mais chaque requête passe quand même, donc une erreur de câblage n'enferme jamais personne dehors.
</Callout>

## 1. Active le mode aperçu

Dans le tableau de bord, ouvre l'équipe et active le **mode aperçu**. Tant qu'il est actif, l'autorisateur de la porte note les décisions défi contre passage direct sur la [page de statistiques](/docs/proxy-page-gate/statistics) mais ne bloque jamais. Tu le désactiveras à la fin.

## 2. Active la porte sur ta clé de site

Ouvre ta clé de site et va à la page **Porte de proxy**. Active **État → Activé**, puis règle :

- **TTL de laissez-passer** : combien de temps une seule résolution dégage un visiteur (par défaut 30 minutes). Plus court veut dire plus de re-contrôles mais une fenêtre plus petite si un cookie est volé.
- **Mode d'échec** : ce que ton proxy fait quand il ne peut pas atteindre l'autorisateur de Caputchin. **Fail-closed** bloque (plus sûr pour un portail de connexion) ; **fail-open** laisse passer les requêtes (évite les coupures sur un site public).

La page montre aussi un extrait nginx prêt à copier avec ta clé de site déjà remplie.

## 3. Autorise l'origine que tu protèges

Le défi ne redirige jamais que vers une **origine autorisée**, la même liste d'origines autorisées qu'utilise le widget. Assure-toi qu'elle inclut l'origine que tu protèges, par exemple `https://auth.example.com`. Mets-la dans la configuration Cap de la clé de site si elle n'y est pas déjà.

## 4. Câble l'autorisateur et la redirection vers le défi

Deux blocs `location` : une sous-requête **autorisateur** interne, et une redirection **défi** vers laquelle le proxy saute sur un `401`. Remplace `YOUR_SITE_KEY` par ta clé publique.

```nginx
# Gate the protected paths.
location / {
  auth_request /_cpt_authz;             # 204 = allow, 401 = challenge
  error_page 401 = @cpt_challenge;
  # ...proxy_pass to your app...
}

location = /_cpt_authz {
  internal;
  proxy_pass https://verify.caputchin.com/v1/gate/authz?site=YOUR_SITE_KEY;
  proxy_pass_request_body off;
  proxy_set_header Content-Length "";
  proxy_set_header Cookie $http_cookie;  # forward the cpt_gate cookie
}

location @cpt_challenge {
  return 302 https://verify.caputchin.com/v1/gate/challenge?site=YOUR_SITE_KEY&return=$scheme://$host$request_uri;
}
```

Mets une porte aux chemins d'entrée (le HTML du portail et le POST de connexion). Ne mets **pas** de porte à la sous-requête de l'autorisateur, aux health checks, ni au callback ci-dessous.

## 5. Ajoute le callback qui pose le cookie

La page du défi se termine en auto-envoyant un petit `POST` vers `/__cpt/callback` sur ton origine, avec `cpt_gate` (le laissez-passer) et `to` (où envoyer le visiteur) dans le **corps**. Un handler minuscule pose le cookie et redirige. Le contrat complet, y compris pourquoi chaque attribut de cookie compte, est dans les [recettes de proxy inverse](/docs/proxy-page-gate/reverse-proxy-recipes#the-callback). Le minimum :

```js
app.post("/__cpt/callback", express.urlencoded({ extended: false }), (req, res) => {
  const pass = String(req.body.cpt_gate || "");
  const to = String(req.body.to || "/");
  const target = new URL(to, `https://${req.headers.host}`);
  if (target.host !== req.headers.host) return res.status(400).end(); // same-origin only
  res.setHeader(
    "Set-Cookie",
    `cpt_gate=${pass}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=1800`
  );
  res.redirect(303, target.pathname + target.search);
});
```

## 6. Observe-la en aperçu

Charge l'URL protégée. Comme l'aperçu est actif, tu passes tout droit, mais la [page de statistiques](/docs/proxy-page-gate/statistics) note un `challenge_served` (tu n'avais pas de cookie) et, une fois que tu résous et que le callback tourne, un `pass_issued`. Recharge et tu devrais voir `passthrough` grimper. Si les défis n'apparaissent jamais, le bloc de l'autorisateur n'est pas atteint ; si le callback renvoie 400, vérifie l'origine `to`.

## 7. Passe en direct

Quand les chiffres ont bonne allure, désactive le **mode aperçu**. La porte fait maintenant respecter la règle : les visiteurs non dégagés sont envoyés au jeu, les visiteurs qui résolvent se promènent jusqu'à ce que leur laissez-passer expire.

## Où aller ensuite

- [Recettes de proxy inverse](/docs/proxy-page-gate/reverse-proxy-recipes) : Traefik, Caddy, et la marche à suivre complète d'Authelia.
- [Statistiques de la porte de proxy](/docs/proxy-page-gate/statistics) : ce que chaque chiffre veut dire une fois en direct.
- [Vue d'ensemble](/docs/proxy-page-gate/overview) : le concept et ce que la porte ne fait délibérément pas.