Configure o portão de página no proxy com nginx

Ao fim deste tutorial o portão estará rodando na frente de um site atrás do nginx: um visitante não liberado é enviado a uma verificação, passar nela define um cookie, e as requisições seguintes passam direto. Você vai observar tudo primeiro em modo prévia, para que nada seja bloqueado até você ter confirmado a ligação. Aqui se usa nginx; as receitas de Traefik, Caddy e Authelia seguem a mesma forma.

1. Ligue o modo prévia

No painel, abra a equipe e ligue o modo prévia. Enquanto está ligado, o autorizador do portão registra as decisões de desafio contra passagem direta na página de estatísticas mas nunca bloqueia. Você vai desligá-lo no fim.

2. Ative o portão na sua chave de site

Abra a sua chave de site e vá à página Portão de proxy. Ligue Status → Ativado, então ajuste:

Tipo de desafio: Jogar um jogo (o padrão) ou Confirmar com uma caixa de seleção. Uma chave de site que exige um jogo sempre mostra um jogo, e a página avisa isso. Escolher um jogo exige pelo menos um jogo instalado com um artefato reproduzível.
TTL de liberação: por quanto tempo uma única resolução libera um visitante (padrão 30 minutos). Mais curto significa mais reconferências mas uma janela menor se um cookie for roubado.
Modo de falha: o que o seu proxy faz quando não consegue alcançar o autorizador do Caputchin. Fail-closed bloqueia (mais seguro para um portal de login); fail-open deixa as requisições passarem (evita indisponibilidade em um site público).

Deixe Idioma e Tema em acompanhar o visitante: a verificação então fala o idioma do visitante, segue a preferência dele por claro ou escuro, e leva a marca desta chave de site automaticamente. Em Avançado você pode renomear o cookie do portão, mover o caminho do callback, e limitar o portão a caminhos específicos; este passo a passo usa os padrões. Veja Personalize o desafio.

A página também mostra um trecho de nginx pronto para copiar com as suas configurações já preenchidas. As configurações levam até dez segundos para chegar à edge depois que você as muda.

3. Permita a origem que você está protegendo

A verificação só redireciona de volta para uma origem permitida, a mesma lista de origens permitidas que o widget usa. Garanta que ela inclua a origem que você está protegendo, por exemplo https://auth.example.com. Defina-a na configuração Cap da chave de site se ainda não estiver lá.

4. Ligue o autorizador e o redirecionamento para o desafio

Dois blocos location: uma sub-requisição autorizador interna, e um redirecionamento desafio para o qual o proxy salta em um 401. Substitua YOUR_SITE_KEY pela sua chave 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;
}

O autorizador só responde 204 ou 401, então qualquer outra coisa, inclusive um timeout, significa que o Caputchin está inalcançável e o seu modo de falha decide. Copie o trecho do painel e ele já vem casado com o modo de falha que você escolheu.

Ponha portão nos caminhos de entrada (o HTML do portal e o POST de login). Não ponha portão na sub-requisição do autorizador, nos health checks, nem no callback abaixo.

A página de verificação termina auto-enviando um pequeno POST para /__cpt/callback na sua origem (ou para o caminho de callback que você definiu), com cpt_gate (o passe) e to (para onde enviar o visitante) no corpo. O campo se chama cpt_gate mesmo que você tenha renomeado o cookie. Um handler minúsculo define o cookie e redireciona. O contrato completo, incluindo por que cada atributo do cookie importa, está nas receitas de proxy reverso. O 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. Observe-o em prévia

Carregue a URL protegida. Como a prévia está ligada, você passa direto, mas a página de estatísticas registra um challenge_served (você não tinha cookie) e, assim que você resolve e o callback roda, um pass_issued. Recarregue e você deve ver passthrough subir. Se os desafios nunca aparecem, o bloco do autorizador não está sendo atingido; se o callback dá 400, confira a origem to.

7. Vá ao ar

Quando os números tiverem boa aparência, desligue o modo prévia. O portão agora faz cumprir: visitantes não liberados são enviados ao jogo, visitantes que resolvem percorrem até o passe deles expirar.

Para onde ir em seguida

Receitas de proxy reverso: Traefik, Caddy, e o passo a passo completo do Authelia.
Estatísticas do portão de página no proxy: o que cada número significa quando você está ao ar.
Visão geral: o conceito e o que o portão deliberadamente não faz.

Configure o portão de página no proxy com nginx

Nesta página