Das Proxy-Gate mit nginx einrichten

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 folgen derselben Form.

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 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.

# 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.

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. Das Minimum:

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 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: Traefik, Caddy, und die volle Authelia-Durchgehung.
Proxy-Gate-Statistik: was jede Zahl bedeutet, sobald du live bist.
Überblick: das Konzept und was das Gate bewusst nicht tut.

Das Proxy-Gate mit nginx einrichten

Auf dieser Seite