Ponha uma porta 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. 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.

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 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 joga o jogo 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 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 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: ative-a e ligue o seu proxy de ponta a ponta.
• Receitas de proxy reverso: nginx, Traefik, Caddy, e o exemplo trabalhado do Authelia.
• Estatísticas da porta de 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.