--- type: explanation title: Ponha uma porta diante de um site inteiro no seu proxy reverso summary: O que é a porta de proxy, para quem ela serve, e como um visitante resolve um jogo para ganhar um passe efêmero que libera as requisições dele, para que você proteja apps onde não dá para incrustar o widget. --- O jeito normal de usar o Caputchin é incrustar o [widget](/docs/site-keys/embedding-the-widget) em uma página e verificar o token a partir do seu backend. Isso precisa de um lugar para colocar o widget e de um backend para conferir o token. A porta de proxy não precisa de nenhum dos dois. Ela coloca uma verificação de página inteira na frente de um site ou rota inteira no seu **proxy reverso**: um visitante resolve um jogo, ganha um passe efêmero, e percorre o site até o passe expirar. A app protegida nunca é tocada. Como nada é adicionado à app em si, este é o jeito de proteger hosts onde você não consegue incrustar um script, um portal de login mono-página compilado, um appliance, ou uma ferramenta interna que fica atrás de um proxy de autenticação. A porta de proxy existe do plano Alpha em diante, ativada por chave de site. O Caputchin hospeda o desafio e emite o passe; você aponta o seu proxy reverso existente (nginx, Traefik, Caddy, ou o que quer que fique na frente da sua app) para ela. ## Para quem serve Recorra à porta quando o widget em linha não se encaixa: - **A app não tem lugar para o widget.** Um portal de login lacrado (como o Authelia), um appliance de fornecedor, ou qualquer UI que você não consegue editar. - **Você quer pôr porta em uma superfície inteira, não em um formulário.** "Prove que você é humano antes de chegar a este site" em vez de uma conferência em um único envio. - **Você não tem backend para verificar um token.** O proxy faz cumprir a regra; não há chamada `/siteverify` para escrever. Para uma página ou formulário normal que você controla, incruste o [widget](/docs/site-keys/embedding-the-widget) em vez disso, ele é mais leve e não redireciona o visitante. Se você tem um formulário mas nenhum backend, a [verificação hospedada](/docs/hosted-verification/overview) se encaixa melhor. ## Como funciona Uma única resolução compra muitas requisições. O visitante joga o jogo uma vez; depois disso, um cookie próprio libera as requisições dele até expirar. ```mermaid sequenceDiagram participant V as Visitante participant P as Seu proxy reverso participant C as Caputchin V->>P: pede uma URL protegida P->>C: checagem authz (encaminha o cookie cpt_gate) C-->>P: 401, ainda sem passe válido P-->>V: 302 para o desafio hospedado V->>C: joga o jogo C-->>V: passe, auto-POST para o seu callback V->>P: POST do passe para /__cpt/callback P-->>V: define o cookie cpt_gate, redireciona de volta V->>P: pede de novo (cookie presente) P->>C: checagem authz C-->>P: 204 permitir P-->>V: sua app responde ``` O proxy faz uma pequena chamada **ao autorizador** do Caputchin a cada requisição. Quando a requisição não leva um passe válido, o Caputchin responde `401` e o proxy redireciona o visitante para o desafio hospedado. Quando o passe está presente e é válido, o Caputchin responde `204` e o proxy deixa a requisição passar para a sua app. ## O cookie de liberação O passe vive em um cookie próprio chamado `cpt_gate`, definido no seu próprio domínio por um pequeno callback que você hospeda. É um token assinado e efêmero, não amarrado a um dispositivo, então a segurança dele vem inteiramente dos atributos do cookie (`HttpOnly`, `Secure`, `SameSite=Lax`) e de uma TTL curta que você escolhe. Como ele define um cookie nos seus visitantes, divulgue isso na sua política de cookies. O [guia de configuração](/docs/proxy-page-gate/set-up) percorre o callback e os atributos exigidos. ## O que é deixado de fora de propósito - **Sem porta auto-hospedada.** O Caputchin hospeda o desafio e verifica o passe; você não roda um verificador. Seu proxy só encaminha um cookie e segue redirecionamentos. - **Uma conferência por requisição, não validação local do token.** O proxy pergunta ao Caputchin a cada requisição. O **modo de falha** que você escolhe (aberto ou fechado) decide o que acontece se o Caputchin ficar um instante inalcançável. - **Liberação por chave de site, com escopo de cookie.** Um passe libera uma origem, não uma conta inteira nem vários domínios, porque é um cookie próprio comum. - **Nem sessão nem login.** A porta prova que um humano chegou ao site; sua app continua cuidando da autenticação e dos seus próprios limites de taxa. As duas se empilham. ## Veja também - [Configurar a porta de proxy](/docs/proxy-page-gate/set-up): ative-a e ligue o seu proxy de ponta a ponta. - [Receitas de proxy reverso](/docs/proxy-page-gate/reverse-proxy-recipes): nginx, Traefik, Caddy, e o exemplo trabalhado do Authelia. - [Estatísticas da porta de proxy](/docs/proxy-page-gate/statistics): leia a razão de passagem direta sobre desafio. - [Verificação hospedada](/docs/hosted-verification/overview): a opção sem backend quando você de fato tem um formulário para apontar para nós.