---
type: tutorial
title: Configure a porta de proxy com nginx
summary: Ative a porta em uma chave de site, ligue um proxy reverso nginx de ponta a ponta, e observe-a em modo prévia antes que ela bloqueie um único visitante real.
---

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](/docs/proxy-page-gate/reverse-proxy-recipes) seguem a mesma forma.

<Callout type="tip">
Faça o passo 1 antes de tocar no seu proxy. O modo prévia deixa a porta rodar só em monitoramento: o painel registra o que ela *teria* feito, mas toda requisição ainda passa, então um erro de ligação nunca tranca ninguém do lado de fora.
</Callout>

## 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](/docs/proxy-page-gate/statistics) 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.

```nginx
# 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.

## 5. Adicione o callback que define o cookie

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](/docs/proxy-page-gate/reverse-proxy-recipes#the-callback). O mínimo:

```js
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](/docs/proxy-page-gate/statistics) 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](/docs/proxy-page-gate/reverse-proxy-recipes): Traefik, Caddy, e o passo a passo completo do Authelia.
- [Estatísticas da porta de proxy](/docs/proxy-page-gate/statistics): o que cada número significa quando você está ao ar.
- [Visão geral](/docs/proxy-page-gate/overview): o conceito e o que a porta deliberadamente não faz.