---
type: tutorial
title: Das Proxy-Gate mit nginx einrichten
summary: Aktiviere das Gate an einem Site-Key, verdrahte einen nginx-Reverse-Proxy von Ende zu Ende, und beobachte es im Vorschaumodus, bevor es einen einzigen echten Besucher blockiert.
---

Am Ende dieses Tutorials läuft das Gate vor einer Site hinter nginx: ein nicht freigegebener Besucher wird zu einem Spiel geschickt, ein gelöstes Spiel setzt ein Cookie, und spätere Anfragen gehen direkt durch. Du beobachtest das Ganze zuerst im **Vorschaumodus**, sodass nichts blockiert wird, bis du die Verdrahtung bestätigt hast. Hier wird nginx verwendet; die [Rezepte für Traefik, Caddy und Authelia](/docs/proxy-page-gate/reverse-proxy-recipes) folgen derselben Form.

<Callout type="tip">
Mach Schritt 1, bevor du deinen Proxy anfasst. Der Vorschaumodus lässt das Gate nur im Monitor-Betrieb laufen: das Dashboard hält fest, was es getan *hätte*, aber jede Anfrage geht weiterhin durch, sodass ein Verdrahtungsfehler nie jemanden aussperrt.
</Callout>

## 1. Schalte den Vorschaumodus ein

Öffne im Dashboard das Team und schalte den **Vorschaumodus** ein. Solange er an ist, hält der Gate-Autorisierer die Entscheidungen Challenge gegen Durchgang auf der [Statistik-Seite](/docs/proxy-page-gate/statistics) fest, blockiert aber nie. Du schaltest ihn am Ende aus.

## 2. Aktiviere das Gate an deinem Site-Key

Öffne deinen Site-Key und geh zur Seite **Proxy-Gate**. Schalte **Status → Aktiviert** ein, dann setze:

- **Freigabe-TTL**: wie lange ein Lösen einen Besucher freigibt (Standard 30 Minuten). Kürzer heißt mehr Neuprüfungen, aber ein kleineres Fenster, falls ein Cookie gestohlen wird.
- **Fail-Modus**: was dein Proxy tut, wenn er Caputchins Autorisierer nicht erreichen kann. **Fail-closed** blockiert (sicherer für ein Login-Portal); **fail-open** lässt Anfragen durch (vermeidet Ausfälle auf einer öffentlichen Site).

Die Seite zeigt außerdem ein fertig zu kopierendes nginx-Snippet mit deinem bereits eingesetzten Site-Key.

## 3. Erlaube den Origin, den du absicherst

Die Challenge leitet immer nur zu einem **erlaubten Origin** zurück, derselben Origin-Allowlist, die das Widget nutzt. Sorg dafür, dass sie den Origin enthält, den du absicherst, zum Beispiel `https://auth.example.com`. Setze ihn in der Cap-Konfiguration des Site-Keys, falls er noch nicht da ist.

## 4. Verdrahte den Autorisierer und die Challenge-Umleitung

Zwei `location`-Blöcke: eine interne **Autorisierer**-Subrequest, und eine **Challenge**-Umleitung, zu der der Proxy bei einem `401` springt. Ersetze `YOUR_SITE_KEY` durch deinen öffentlichen Key.

```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;
}
```

Sichere die Einstiegspfade ab (das Portal-HTML und den Login-POST). Sichere **nicht** die Autorisierer-Subrequest, Health-Checks, oder den Callback unten ab.

## 5. Füge den Callback hinzu, der das Cookie setzt

Die Challenge-Seite schließt ab, indem sie einen kleinen `POST` an `/__cpt/callback` auf deinem Origin auto-absendet, mit `cpt_gate` (dem Pass) und `to` (wohin der Besucher geschickt wird) im **Body**. Ein winziger Handler setzt das Cookie und leitet um. Der volle Vertrag, samt warum jedes Cookie-Attribut zählt, steht in den [Reverse-Proxy-Rezepten](/docs/proxy-page-gate/reverse-proxy-recipes#the-callback). Das 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. Beobachte es in der Vorschau

Lade die abgesicherte URL. Weil die Vorschau an ist, gehst du direkt durch, aber die [Statistik-Seite](/docs/proxy-page-gate/statistics) hält ein `challenge_served` fest (du hattest kein Cookie) und, sobald du löst und der Callback läuft, ein `pass_issued`. Lade neu, und du solltest `passthrough` klettern sehen. Erscheinen nie Challenges, wird der Autorisierer-Block nicht getroffen; gibt der Callback ein 400 zurück, prüf den `to`-Origin.

## 7. Geh live

Wenn die Zahlen richtig aussehen, schalte den **Vorschaumodus** aus. Das Gate setzt jetzt durch: nicht freigegebene Besucher werden zum Spiel geschickt, gelöste Besucher streifen, bis ihr Pass abläuft.

## Wohin als Nächstes

- [Reverse-Proxy-Rezepte](/docs/proxy-page-gate/reverse-proxy-recipes): Traefik, Caddy, und die volle Authelia-Durchgehung.
- [Proxy-Gate-Statistik](/docs/proxy-page-gate/statistics): was jede Zahl bedeutet, sobald du live bist.
- [Überblick](/docs/proxy-page-gate/overview): das Konzept und was das Gate bewusst nicht tut.