Das Proxy-Seiten-Gate mit nginx einrichten

Am Ende dieses Tutorials läuft das Gate vor einer Site hinter nginx: ein nicht freigegebener Besucher wird zu einer Verifizierung geschickt, sie zu bestehen 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 Aufgabe 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:

Aufgabentyp: Ein Spiel spielen (der Standard) oder Mit einer Checkbox bestätigen. Ein Site-Key, der ein Spiel verlangt, zeigt immer ein Spiel, und die Seite sagt das auch. Ein Spiel zu wählen braucht mindestens ein installiertes Spiel mit einem abspielbaren Artefakt.
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).

Lass Sprache und Design auf dem Besucher folgen: die Verifizierung spricht dann die Sprache des Besuchers, folgt seiner Hell- oder Dunkel-Vorliebe, und trägt automatisch das Branding dieses Site-Keys. Unter Erweitert kannst du das Gate-Cookie umbenennen, den Callback-Pfad verschieben, und das Gate auf bestimmte Pfade beschränken; diese Durchgehung nutzt die Standardwerte. Siehe Die Aufgabe anpassen.

Die Seite zeigt außerdem ein fertig zu kopierendes nginx-Snippet mit deinen bereits eingesetzten Einstellungen. Einstellungen brauchen bis zu zehn Sekunden, bis sie nach einer Änderung am Edge ankommen.

3. Erlaube den Origin, den du absicherst

Die Verifizierung 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 Aufgaben-Umleitung

Zwei location-Blöcke: eine interne Autorisierer-Subrequest, und eine Aufgaben-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_intercept_errors on;
  error_page 500 502 503 504 = @cpt_unreachable;
  # ...proxy_pass to your app...
}

location = /_cpt_authz {
  internal;
  auth_request off;
  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
  proxy_connect_timeout 2s;
  proxy_read_timeout 2s;
}

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

# This is your fail mode. `return 403` blocks when Caputchin is unreachable
# (fail closed); `return 204` lets the request through (fail open).
location @cpt_unreachable {
  return 403;
}

Der Autorisierer antwortet immer nur 204 oder 401, also heißt alles andere, Timeout eingeschlossen, dass Caputchin nicht erreichbar ist und dein Fail-Modus entscheidet. Kopier das Snippet aus dem Dashboard, und es passt bereits zu dem Fail-Modus, den du gewählt hast.

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

Die Verifizierungsseite schließt ab, indem sie einen kleinen POST an /__cpt/callback auf deinem Origin auto-absendet (oder an den Callback-Pfad, den du gesetzt hast), mit cpt_gate (dem Pass) und to (wohin der Besucher geschickt wird) im Body. Das Feld heißt cpt_gate, auch wenn du das Cookie umbenannt hast. 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 Aufgaben, 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-Seiten-Gate-Statistik: was jede Zahl bedeutet, sobald du live bist.
Überblick: das Konzept und was das Gate bewusst nicht tut.

Das Proxy-Seiten-Gate mit nginx einrichten

Auf dieser Seite