Configure a porta de proxy com nginx

Ao fim deste tutorial a porta estará rodando na frente de um site atrás do nginx: um visitante não liberado é enviado a um jogo, um jogo resolvido 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 da porta 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 a porta na sua chave de site

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

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).

A página também mostra um trecho de nginx pronto para copiar com a sua chave de site já preenchida.

3. Permita a origem que você está protegendo

O desafio 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_pass to your app...
}

location = /_cpt_authz {
  internal;
  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
}

location @cpt_challenge {
  return 302 https://verify.caputchin.com/v1/gate/challenge?site=YOUR_SITE_KEY&return=$scheme://$host$request_uri;
}

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

A página do desafio termina auto-enviando um pequeno POST para /__cpt/callback na sua origem, com cpt_gate (o passe) e to (para onde enviar o visitante) no corpo. 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-a 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. A porta 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 da porta de proxy: o que cada número significa quando você está ao ar.
Visão geral: o conceito e o que a porta deliberadamente não faz.

Configure a porta de proxy com nginx

Nesta página