Configura la puerta de página en el proxy con nginx

Al final de este tutorial la puerta estará corriendo delante de un sitio detrás de nginx: un visitante sin despejar es enviado a una verificación, superarla fija una cookie, y las peticiones posteriores pasan de largo. Verás todo el proceso primero en modo vista previa, así nada se bloquea hasta que hayas confirmado el cableado. Aquí se usa nginx; las recetas de Traefik, Caddy y Authelia siguen la misma forma.

1. Enciende el modo vista previa

En el dashboard, abre el equipo y enciende el modo vista previa. Mientras está encendido, el autorizador de la puerta registra las decisiones de reto frente a paso libre en la página de estadísticas pero nunca bloquea. Lo apagarás al final.

2. Activa la puerta en tu clave de sitio

Abre tu clave de sitio y ve a la página Puerta de proxy. Enciende Estado → Activado, luego ajusta:

Tipo de reto: Jugar un juego (por defecto) o Confirmar con una casilla. Una clave de sitio que exige un juego muestra siempre un juego, y la página lo dice. Elegir un juego requiere al menos un juego instalado con un artefacto reproducible.
TTL de paso libre: cuánto tiempo despeja a un visitante una sola resolución (por defecto 30 minutos). Más corto significa más re-comprobaciones pero una ventana más pequeña si roban una cookie.
Modo de fallo: qué hace tu proxy cuando no puede alcanzar al autorizador de Caputchin. Fallo cerrado bloquea (más seguro para un portal de inicio de sesión); fallo abierto deja pasar las peticiones (evita caídas en un sitio público).

Deja Idioma y Tema en coincidir con el visitante: la verificación habla entonces el idioma del visitante, sigue su preferencia de claro u oscuro, y lleva automáticamente la marca de esta clave de sitio. Bajo Avanzado puedes renombrar la cookie de la puerta, mover la ruta del callback, y acotar la puerta a rutas concretas; este recorrido usa los valores por defecto. Consulta Personaliza el reto.

La página también muestra un fragmento de nginx listo para copiar con tus ajustes ya rellenados. Los ajustes tardan hasta diez segundos en llegar al borde después de que los cambies.

3. Permite el origen que estás cerrando con puerta

La verificación solo redirige de vuelta a un origen permitido, la misma lista de orígenes permitidos que usa el widget. Asegúrate de que incluya el origen que estás cerrando con puerta, por ejemplo https://auth.example.com. Ponlo en la configuración Cap de la clave de sitio si no está ya ahí.

4. Cablea el autorizador y la redirección al reto

Dos bloques location: una subpetición autorizador interna, y una redirección reto a la que el proxy salta ante un 401. Reemplaza YOUR_SITE_KEY con tu clave pública.

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

El autorizador solo responde 204 o 401, así que cualquier otra cosa, incluido un timeout, significa que Caputchin es inalcanzable y decide tu modo de fallo. Copia el fragmento del dashboard y ya vendrá con el modo de fallo que elegiste.

Pon puerta a las rutas de entrada (el HTML del portal y el POST de inicio de sesión). No pongas puerta a la subpetición del autorizador, a los health checks, ni al callback de abajo.

La página de verificación termina auto-enviando un pequeño POST a /__cpt/callback en tu origen (o a la ruta de callback que hayas puesto), con cpt_gate (el pase) y to (a dónde enviar al visitante) en el cuerpo. El campo se llama cpt_gate aunque hayas renombrado la cookie. Un manejador diminuto fija la cookie y redirige. El contrato completo, incluyendo por qué importa cada atributo de la cookie, está en las recetas de proxy inverso. Lo mínimo:

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. Obsérvala en vista previa

Carga la URL con puerta. Como la vista previa está encendida, pasas de largo, pero la página de estadísticas registra un challenge_served (no tenías cookie) y, una vez que resuelves y corre el callback, un pass_issued. Recarga y deberías ver passthrough subir. Si los retos nunca aparecen, el bloque del autorizador no se está alcanzando; si el callback devuelve 400, revisa el origen to.

7. Sal en vivo

Cuando los números pinten bien, apaga el modo vista previa. La puerta ahora hace cumplir: los visitantes sin despejar son enviados al juego, los visitantes que resuelven recorren hasta que su pase expira.

Adónde ir después

Recetas de proxy inverso: Traefik, Caddy, y el recorrido completo de Authelia.
Estadísticas de la puerta de página en el proxy: qué significa cada número una vez estás en vivo.
Panorama: el concepto y lo que la puerta deliberadamente no hace.

Configura la puerta de página en el proxy con nginx

En esta página