Ponha um portão diante de um site inteiro no seu proxy reverso

O jeito normal de usar o Caputchin é incrustar o 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. O portão de página no proxy não precisa de nenhum dos dois. Ele coloca uma verificação de página inteira na frente de um site ou rota inteira no seu proxy reverso: um visitante completa uma verificação, ganha um passe efêmero, e percorre o site até o passe expirar. A verificação é um jogo curto ou uma confirmação de um toque só, o que você escolher. 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.

Para quem serve

Recorra ao portão 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 portão 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 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 se encaixa melhor.

Como funciona

Uma única resolução compra muitas requisições. O visitante completa a verificação uma vez; depois disso, um cookie próprio libera as requisições dele até expirar.

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 passe vive em um cookie próprio, chamado cpt_gate por padrão e renomeável por chave de site, definido no seu próprio domínio por um pequeno callback que você hospeda (em /__cpt/callback por padrão, também renomeável). É 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 percorre o callback e os atributos exigidos.

O que é deixado de fora de propósito

Sem portão auto-hospedado. 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.
Sem texto personalizado. Você escolhe o idioma e o tema da página de verificação, não o texto dela.
Nem sessão nem login. O portão 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.

O que o visitante vê

A página de verificação fala o próprio idioma do visitante e segue a preferência dele por claro ou escuro, e leva a mesma marca que o widget desta chave de site, porque ela resolve as duas coisas a partir da mesma chave de site que você já configurou. Você pode fixar um idioma ou um tema em vez disso, e escolher entre um jogo e uma caixa de seleção de um toque só, na página Portão de proxy da chave de site. Veja Personalize o desafio.

Veja também

Configurar o portão de página no proxy: ative-o e ligue o seu proxy de ponta a ponta.
Personalize o desafio: jogo ou caixa de seleção, idioma, tema, nome do cookie, caminho do callback.
Receitas de proxy reverso: nginx, Traefik, Caddy, e o exemplo trabalhado do Authelia.
Estatísticas do portão de página no proxy: leia a razão de passagem direta sobre desafio.
Verificação hospedada: a opção sem backend quando você de fato tem um formulário para apontar para nós.