--- type: explanation title: Pon una puerta a un sitio entero en tu proxy inverso summary: Qué es la puerta de proxy, para quién es, y cómo un visitante resuelve un juego para ganar un pase efímero que despeja sus peticiones, para que protejas apps donde no puedes incrustar el widget. --- La forma normal de usar Caputchin es incrustar el [widget](/docs/site-keys/embedding-the-widget) en una página y verificar el token desde tu backend. Eso necesita un lugar donde poner el widget y un backend que compruebe el token. La puerta de proxy no necesita ninguno de los dos. Pone una verificación a página completa delante de un sitio o ruta entera en tu **proxy inverso**: un visitante resuelve un juego, gana un pase efímero, y recorre el sitio hasta que el pase expira. La app protegida nunca se toca. Como no se añade nada a la app en sí, esta es la manera de proteger hosts donde no puedes incrustar un script, un portal de inicio de sesión compilado de una sola página, un appliance, o una herramienta interna que vive tras un proxy de autenticación. La puerta de proxy está en el plan Alpha en adelante, activada por clave de sitio. Caputchin aloja el reto y emite el pase; tú apuntas hacia ella tu proxy inverso existente (nginx, Traefik, Caddy, o lo que dé la cara por tu app). ## Para quién es Recurre a la puerta cuando el widget en línea no encaja: - **La app no tiene sitio para el widget.** Un portal de inicio de sesión sellado (como Authelia), un appliance de proveedor, o cualquier UI que no puedes editar. - **Quieres poner puerta a una superficie entera, no a un formulario.** "Demuestra que eres humano antes de llegar a este sitio" en vez de una comprobación en un único envío. - **No tienes backend para verificar un token.** El proxy hace de guardián; no hay llamada `/siteverify` que escribir. Para una página o formulario normal que controlas, incrusta el [widget](/docs/site-keys/embedding-the-widget) en su lugar, es más ligero y no redirige al visitante. Si tienes un formulario pero no backend, la [verificación alojada](/docs/hosted-verification/overview) encaja mejor. ## Cómo funciona Una sola resolución compra muchas peticiones. El visitante juega el juego una vez; después de eso, una cookie de origen despeja sus peticiones hasta que expira. ```mermaid sequenceDiagram participant V as Visitante participant P as Tu proxy inverso participant C as Caputchin V->>P: pide una URL con puerta P->>C: chequeo de authz (reenvía la cookie cpt_gate) C-->>P: 401, aún sin pase válido P-->>V: 302 al reto alojado V->>C: juega el juego C-->>V: pase, auto-POST a tu callback V->>P: POST del pase a /__cpt/callback P-->>V: fija la cookie cpt_gate, redirige de vuelta V->>P: pide de nuevo (cookie presente) P->>C: chequeo de authz C-->>P: 204 permitir P-->>V: tu app responde ``` El proxy hace una pequeña llamada **al autorizador** de Caputchin en cada petición. Cuando la petición no lleva un pase válido, Caputchin responde `401` y el proxy redirige al visitante al reto alojado. Cuando el pase está presente y es válido, Caputchin responde `204` y el proxy deja pasar la petición hacia tu app. ## La cookie de paso libre El pase vive en una cookie de origen llamada `cpt_gate`, fijada en tu propio dominio por un pequeño callback que alojas. Es un token firmado y efímero, no atado a un dispositivo, así que su seguridad viene enteramente de los atributos de la cookie (`HttpOnly`, `Secure`, `SameSite=Lax`) y un TTL corto que eliges. Como fija una cookie en tus visitantes, decláralo en tu política de cookies. La [guía de configuración](/docs/proxy-page-gate/set-up) recorre el callback y los atributos requeridos. ## Qué se deja fuera a propósito - **Sin puerta autoalojada.** Caputchin aloja el reto y verifica el pase; tú no corres un verificador. Tu proxy solo reenvía una cookie y sigue redirecciones. - **Una comprobación por petición, no validación local del token.** El proxy pregunta a Caputchin en cada petición. El **modo de fallo** que elijas (abierto o cerrado) decide qué pasa si Caputchin queda un momento inalcanzable. - **Paso por clave de sitio, con alcance de cookie.** Un pase despeja un origen, no una cuenta entera ni varios dominios, porque es una cookie de origen corriente. - **No es una sesión ni un inicio de sesión.** La puerta prueba que un humano llegó al sitio; tu app sigue encargándose de la autenticación y sus propios límites de tasa. Los dos se apilan. ## Véase también - [Configura la puerta de proxy](/docs/proxy-page-gate/set-up): actívala y cablea tu proxy de extremo a extremo. - [Recetas de proxy inverso](/docs/proxy-page-gate/reverse-proxy-recipes): nginx, Traefik, Caddy, y el ejemplo resuelto de Authelia. - [Estadísticas de la puerta de proxy](/docs/proxy-page-gate/statistics): lee la razón de paso libre frente a reto. - [Verificación alojada](/docs/hosted-verification/overview): la opción sin backend cuando sí tienes un formulario que apuntarnos.