SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-11-06

Coloque qualquer app atrás de SSO com oauth2-proxy

Veja como usar oauth2-proxy com Nginx ou Traefik para proteger apps sem login via OIDC, com forward auth e correção de cookies e redirecionamentos.

Autenticação encaminhada: como uma aplicação sem login obtém SSO

O oauth2-proxy fornece início de sessão único a uma aplicação que não tem o seu próprio login. Isto funciona porque o reverse proxy à frente da aplicação bloqueia todos os pedidos, pergunta ao oauth2-proxy se o pedido contém uma sessão válida e encaminha o pedido para o upstream apenas quando a resposta é afirmativa. O código da aplicação não sofre alterações, porque a aplicação nunca vê esta verificação.

A verificação consiste num pedido HTTP adicional. O proxy envia uma cópia dos cabeçalhos do pedido recebido para /oauth2/auth e lê o código de estado. O código 202 indica que a verificação foi aprovada, pelo que o proxy encaminha o pedido original para a aplicação. O código 401 indica que não existe uma sessão válida, pelo que o proxy redireciona o browser para /oauth2/sign_in, que apresenta uma página de login por predefinição. /oauth2/start inicia um login OpenID Connect (OIDC) no seu fornecedor de identidade; skip_provider_button = true faz com que /oauth2/sign_in o inicie automaticamente. O OIDC é a camada de identidade construída sobre o OAuth 2.0, e o fornecedor é o sistema que já utiliza para os logins.

Este padrão tem um nome em todos os reverse proxies. O Nginx chama à diretiva auth_request. O Traefik chama ao middleware forwardAuth. O Caddy designa-o como forward_auth. O serviço que responde ao subpedido também pode ser substituído. O oauth2-proxy é a opção mais comum porque suporta OIDC diretamente e não precisa da sua própria base de dados.

Desenhe o limite de confiança antes de escrever qualquer configuração

Depois de uma verificação bem-sucedida, o oauth2-proxy devolve a identidade nos cabeçalhos da resposta, e o reverse proxy copia-os para o pedido enviado ao upstream. Com set_xauthrequest ativado, obtém X-Auth-Request-User e X-Auth-Request-Email. A aplicação lê esses cabeçalhos e confia neles.

Esse é todo o modelo de segurança, por isso é importante explicitar a consequência. Qualquer processo que consiga abrir uma ligação TCP à porta da aplicação pode definir esses cabeçalhos e assumir a identidade de qualquer utilizador. Um único curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ permite contornar completamente a proteção se alcançar a aplicação diretamente.

Por isso, a aplicação não pode estar acessível por outro meio que não seja o proxy. No Docker Compose, remova o mapeamento ports: do serviço da aplicação e mantenha-o na rede interna, para que apenas o contentor do proxy possa estabelecer ligações com ela. Num host sem contentores, associe a aplicação a 127.0.0.1:3000 em vez de 0.0.0.0:3000. Depois, confirme o que está efetivamente exposto:

sudo ss -tlnp | grep 3000

Uma linha com 0.0.0.0:3000 significa que a aplicação responde no IP público e que a sua proteção é apenas decorativa. 127.0.0.1:3000 é o resultado pretendido. Uma regra de firewall é uma segunda camada útil, mas o endereço de associação é o que continua válido mesmo que outra ferramenta limpe o seu conjunto de regras.

Instalar o oauth2-proxy

Em outubro de 2026, a versão atual é a v7.15.5, publicada em 1 de outubro de 2026. Esta versão corrige dois avisos de segurança críticos. Um deles permite contornar skip_auth_routes e afeta todas as versões posteriores à v7.5.0. Por isso, não instale versões mais antigas. Instale o binário e valide o download:

cd /tmp
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
sha256sum -c oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
tar -xzf oauth2-proxy-v7.15.5.linux-amd64.tar.gz
sudo install -m 755 oauth2-proxy-v7.15.5.linux-amd64/oauth2-proxy /usr/local/bin/oauth2-proxy
oauth2-proxy --version

sha256sum -c deve imprimir uma linha terminada em OK. Se imprimir FAILED, pare e faça novamente o download, em vez de executar o binário.

No Docker, a imagem é quay.io/oauth2-proxy/oauth2-proxy e deve fixar a tag: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5. Deixá-la como latest transforma uma docker compose pull de rotina numa atualização não planeada do único processo que protege todas as aplicações no servidor.

O cookie de sessão é encriptado, e cookie_secret é a chave. A chave de encriptação tem de ter exatamente 16, 24 ou 32 bytes, porque se torna numa chave AES (advanced encryption standard). O oauth2-proxy aceita um valor base64 seguro para URLs que, depois de descodificado, tenha um desses comprimentos, ou um segredo bruto com um desses comprimentos. Caso contrário, recusa iniciar e apresenta um erro de arranque que identifica o segredo do cookie. O comando abaixo produz um valor com 44 caracteres que codifica uma chave de 32 bytes.

openssl rand -base64 32 | tr -- '+/' '-_'

O tr não é apenas cosmético. Converte base64 padrão no alfabeto seguro para URLs que o oauth2-proxy utiliza ao descodificar o segredo.

Siga duas regras para este valor. Use um segredo diferente em cada deployment. Se executar mais de uma instância do oauth2-proxy atrás do mesmo domínio, atribua-lhes o mesmo segredo, porque um cookie encriptado por uma instância tem de poder ser lido pelas outras.

Escreva a configuração do oauth2-proxy

Mantenha as definições num ficheiro em vez de usar uma linha de comandos longa, para que o segredo do cliente nunca apareça no resultado de ps.

# /etc/oauth2-proxy/oauth2-proxy.cfg
http_address = "127.0.0.1:4180"
reverse_proxy = true

provider = "oidc"
oidc_issuer_url = "https://id.example.com/application/o/myapp/"
client_id = "REPLACE_ME"
client_secret = "REPLACE_ME"

redirect_url = "https://app.example.com/oauth2/callback"
cookie_secret = "REPLACE_ME"
cookie_secure = true
cookie_domains = [".example.com"]
whitelist_domains = [".example.com"]

email_domains = ["*"]
set_xauthrequest = true
upstreams = ["static://202"]

reverse_proxy = true diz ao oauth2-proxy para confiar nos cabeçalhos X-Forwarded-* enviados pelo proxy que está à sua frente. Sem esta opção, o oauth2-proxy trata o próprio endereço do proxy como o endereço do cliente e pode avaliar incorretamente se o pedido chegou através de HTTPS.

trusted_proxy_ips limita os pares que podem fornecer esses cabeçalhos. Por predefinição, confia em todas as origens. Isto só é seguro neste caso porque http_address mantém o oauth2-proxy em 127.0.0.1. Se o oauth2-proxy escutar numa rede Docker, defina esta opção com o endereço do reverse proxy.

upstreams = ["static://202"] faz com que o oauth2-proxy responda com 202 a um pedido autenticado e não faça proxy de nada. É exatamente isso que a autenticação de encaminhamento precisa, porque o reverse proxy faz o encaminhamento. Na outra arquitetura, o oauth2-proxy fica diretamente no caminho dos pedidos com upstreams = ["http://127.0.0.1:3000"] e sem qualquer auth_request. Esta opção é mais simples para uma aplicação, mas não escala para dez.

email_domains = ["*"] permite todos os endereços que o seu fornecedor autenticar. Restrinja-o ao seu próprio domínio ou, melhor ainda, limite o acesso com uma associação a um grupo no fornecedor, porque é aí que já gere os utilizadores.

Execute-o com o systemd como um utilizador próprio:

# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target

[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
sudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2-proxy
sudo install -d -m 750 /etc/oauth2-proxy
sudo chown -R oauth2-proxy:oauth2-proxy /etc/oauth2-proxy
sudo chmod 600 /etc/oauth2-proxy/oauth2-proxy.cfg
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2-proxy
curl -s http://127.0.0.1:4180/ping

/ping a imprimir OK significa que o processo arrancou e carregou a configuração. Este é o próprio endpoint de estado do oauth2-proxy e nunca pede uma sessão. Se não houver resposta, consulte journalctl -u oauth2-proxy -n 50, porque um URL do emissor incorreto e um segredo de cookie com comprimento errado fazem ambos o processo falhar no arranque e ambos deixam essa indicação.

Registre o URI de redirecionamento no seu provedor

Crie uma aplicação OIDC no seu provedor e defina o URI de redirecionamento exatamente como o redirect_url da configuração: https://app.example.com/oauth2/callback. Exatamente significa que o esquema, o host, a porta e o caminho devem corresponder carácter a carácter. Uma barra final transforma-o num URI diferente.

Esta é a falha mais comum em toda a configuração e ocorre antes de o oauth2-proxy participar. O provedor rejeita o pedido de autorização e apresenta a sua própria página de erro. Por isso, nada aparece no log do oauth2-proxy. O indício está na barra de endereço: o navegador ainda está no domínio do provedor, e a cadeia de consulta contém error=invalid_request ou a página apresenta diretamente redirect_uri. Quando isso ocorrer, corrija o registo da aplicação no provedor, não a configuração do proxy.

Copie o URL do issuer a partir do provedor, em vez de o escrever manualmente. O oauth2-proxy acrescenta /.well-known/openid-configuration a oidc_issuer_url e obtém esse documento de descoberta durante o arranque. Verifique-o primeiro:

curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400

Um JSON que contenha uma chave authorization_endpoint é uma primeira verificação. O issuer do documento também deve corresponder exatamente a oidc_issuer_url. Um 404 ou uma página de erro HTML indica que o URL está incorreto, e o oauth2-proxy falhará ao arrancar com esse mesmo 404. Se ainda não escolheu um provedor, a comparação entre Keycloak, Authentik e Zitadel apresenta os compromissos de cada opção, e executar o Authentik como o seu próprio servidor SSO explica a parte do provedor nesta configuração específica.

Nginx: auth_request

O Nginx faz autenticação delegada com auth_request, que executa uma sub-requisição interna e toma uma decisão com base no respetivo código de estado.

# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 443 ssl;
  server_name app.example.com;

  location /oauth2/ {
    proxy_pass       http://127.0.0.1:4180;
    proxy_set_header Host                    $host;
    proxy_set_header X-Real-IP               $remote_addr;
    proxy_set_header X-Auth-Request-Redirect $request_uri;
  }

  location = /oauth2/auth {
    proxy_pass       http://127.0.0.1:4180;
    proxy_set_header Host             $host;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-Uri  $request_uri;
    proxy_set_header Content-Length   "";
    proxy_pass_request_body           off;
  }

  location / {
    auth_request /oauth2/auth;
    error_page 401 = @oauth2_signin;

    auth_request_set $user  $upstream_http_x_auth_request_user;
    auth_request_set $email $upstream_http_x_auth_request_email;
    proxy_set_header X-User  $user;
    proxy_set_header X-Email $email;

    auth_request_set $auth_cookie $upstream_http_set_cookie;
    add_header Set-Cookie $auth_cookie;

    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host       $host;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }

  location @oauth2_signin {
    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
  }
}

Há três detalhes importantes neste bloco. proxy_pass_request_body off com um Content-Length vazio impede o nginx de encaminhar um corpo de pedido para o endpoint de autenticação, que precisa apenas dos cabeçalhos.

O par auth_request_set $auth_cookie e add_header Set-Cookie devolve um cookie de sessão atualizado ao navegador. Se o omitir, cookie_refresh não faz nada de forma silenciosa, porque o nginx descarta o Set-Cookie da sub-requisição e o navegador mantém o valor antigo até a sessão expirar. Este par trata um cookie. Cookies de sessão divididos precisam de tratamento adicional para as restantes partes ou de armazenamento de sessão no Redis.

error_page 401 = @oauth2_signin é o que transforma uma verificação falhada num início de sessão. Sem ele, um visitante não autenticado recebe uma página 401 Authorization Required simples e não tem como prosseguir.

Teste antes de recarregar, sempre:

sudo nginx -t && sudo systemctl reload nginx

Se as diretivas envolventes forem novas para si, a anatomia de uma configuração de reverse proxy do nginx explica a camada subjacente a esta.

Traefik: middleware forwardAuth

O Traefik precisa de dois middlewares para a mesma tarefa. Um executa a verificação. O outro apresenta a página de início de sessão quando a verificação falha.

# dynamic configuration
http:
  middlewares:
    oauth-auth:
      forwardAuth:
        address: https://oauth.example.com/oauth2/auth
        trustForwardHeader: true
    oauth-errors:
      errors:
        status:
          - "401-403"
        service: oauth-backend
        query: "/oauth2/sign_in?rd={url}"

Associe ambos ao router que fica à frente da aplicação, com oauth-errors antes de oauth-auth, e publique o oauth2-proxy no seu próprio router em oauth.example.com, porque o browser tem de conseguir aceder a /oauth2/sign_in e /oauth2/callback sem passar pela verificação. Para este host de início de sessão separado, defina redirect_url como https://oauth.example.com/oauth2/callback e registe esse URI no provider.

Com a configuração anterior do oauth2-proxy, /oauth2/sign_in apresenta uma página de início de sessão. Para usar um redirecionamento automático, defina skip_provider_button = true no oauth2-proxy e adicione statusRewrites: {"401": 302} às definições errors do Traefik. Sem essa reescrita, o Traefik devolve o redirecionamento automático com o estado 401 e o browser não o segue. A reescrita, por si só, não inicia o fluxo de início de sessão.

trustForwardHeader: true confia nos cabeçalhos X-Forwarded-* recebidos; o Traefik fornece o host e o URI originais ao oauth2-proxy. A opção está obsoleta na documentação atual do Traefik. Defina whitelist_domains para abranger também esse host; caso contrário, o oauth2-proxy elimina o parâmetro rd por o considerar um risco de redirecionamento aberto e todos chegam a / depois do início de sessão. Um servidor Traefik normalmente fica à frente de várias aplicações ao mesmo tempo, e encaminhar várias aplicações Docker Compose através de uma única instância do Traefik mostra a estrutura dos routers onde isto é integrado.

Caddy: forward_auth

app.example.com {
  handle /oauth2/* {
    reverse_proxy 127.0.0.1:4180 {
      header_up X-Real-IP {remote_host}
      header_up X-Forwarded-Uri {uri}
    }
  }
  handle {
    forward_auth 127.0.0.1:4180 {
      uri /oauth2/auth
      header_up X-Real-IP {remote_host}
      copy_headers X-Auth-Request-User X-Auth-Request-Email
      @error status 401
      handle_response @error {
        redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
      }
    }
    reverse_proxy 127.0.0.1:3000
  }
}

A ordem é importante. O bloco /oauth2/* aparece primeiro e não contém forward_auth, porque um visitante que não tenha iniciado sessão precisa de conseguir aceder aos caminhos de início de sessão e de callback. Se colocar a verificação à frente desses caminhos, o redirecionamento de início de sessão aponta para si próprio até o navegador desistir.

O copy_headers transporta a identidade para o pedido enviado ao upstream e só produz valores quando o oauth2-proxy é executado com set_xauthrequest = true. A escolha entre os proxies é uma questão separada, e a comparação entre nginx, Caddy e Traefik explica esse ponto.

Por que o login volta para a página de login?

Você inicia sessão no provedor, ele redireciona você de volta, e o oauth2-proxy redireciona você novamente para o login. O loop significa que o oauth2-proxy não está aceitando uma sessão válida na solicitação seguinte. O cookie de sessão pode estar ausente ou presente, mas falhar na validação, por exemplo, quando as instâncias usam segredos de cookie diferentes. Abra as ferramentas de desenvolvimento do navegador, localize a solicitação para /oauth2/callback que ocorre depois do redirecionamento de volta do provedor e leia o cabeçalho de resposta Set-Cookie. Um cookie definido nessa resposta e ausente na solicitação seguinte é o cookie que o navegador está recusando. Se ele estiver presente, verifique o log do servidor em busca de erros de validação, como cookie signature not valid, e confirme que todas as instâncias usam o mesmo segredo.

Quando o cookie que desaparece é o cookie CSRF definido pelo oauth2-proxy durante o redirecionamento de saída, o fluxo não entra em loop. Ele para no callback, e o log identifica o caso:

No cookies were found in OAuth callback.

ou, quando algum outro cookie chega, mas o cookie correto não:

Cookies were found in OAuth callback, but none was a CSRF cookie.

CSRF significa falsificação de solicitação entre sites, e esse cookie existe para associar um callback ao login que o iniciou. O navegador exibe uma página de erro 403 contendo:

Login Failed: Unable to find a valid CSRF token. Please try again.

Os cookies ausentes compartilham as três primeiras causas abaixo; a diferença de relógio é outra causa de falhas de validação. Verifique estas quatro causas nesta ordem.

  1. cookie_secure = true enquanto o navegador acessou o site por HTTP simples. Exceto em localhost, um navegador não armazena um cookie marcado como Secure em uma origem http://, portanto nunca o envia de volta. Termine o TLS (segurança da camada de transporte) corretamente ou defina cookie_secure = false apenas durante testes em localhost.
  2. Um valor cookie_domains que não abrange o hostname exibido na barra de endereços. .example.com abrange app.example.com e não faz absolutamente nada para app.example.net.
  3. O navegador está descartando o cookie. Uma extensão de privacidade rigorosa ou o bloqueio de cookies de terceiros pode remover _oauth2_proxy_csrf entre o redirecionamento de saída e o callback, ou o cookie de sessão depois disso.
  4. Diferença de relógio. Se o relógio do servidor estiver muito adiantado em relação ao do provedor, o token de ID poderá parecer expirado e falhar na validação. timedatectl deve informar System clock synchronized: yes.

Outra causa produz o erro CSRF sem haver nada configurado incorretamente. Por padrão, o oauth2-proxy mantém um único cookie CSRF, portanto duas abas que iniciam um login ao mesmo tempo sobrescrevem o cookie uma da outra. cookie_csrf_per_request = true atribui um cookie próprio a cada login.

Observe o problema no lado do servidor em vez de tentar adivinhar:

sudo journalctl -u oauth2-proxy -f

Abra a aplicação em uma janela privada. Cada solicitação é registrada com seu status, portanto um callback seguido imediatamente por outro redirecionamento para o login é o loop, registrado no log.

Caminhos que devem ignorar o login: APIs, webhooks e websockets

A autenticação de encaminhamento pressupõe um navegador que mantém um cookie. Clientes sem navegador falham.

Um cliente de API que envia Authorization: Bearer <token> não tem cookie. Por isso, as configurações do proxy acima encaminham-no para a página de login do oauth2-proxy, a menos que a autenticação com bearer token esteja ativada. Há duas soluções simples. Definir skip_jwt_bearer_tokens = true faz com que o oauth2-proxy aceite um bearer token JWT (JSON web token) válido, emitido pelo issuer configurado e com um audience aceite para este cliente. Isto é adequado quando os clientes da API já obtêm tokens compatíveis do provider. O aud do token deve corresponder a client_id ou a um audience configurado através de extra_jwt_issuers. Em alternativa, exclua o caminho:

skip_auth_routes = [
  "^/api/",
  "POST=^/webhook/",
  "GET=^/healthz$"
]

Cada valor é uma expressão regular comparada com o caminho descodificado sem parâmetros de consulta, opcionalmente precedida por um método HTTP e =. POST=^/webhook/ deixa o receptor de webhook aberto a POST, enquanto um utilizador que navegue para o mesmo caminho continua a ser encaminhado para o login, desde que o pedido de autenticação preserve o método original. Nginx auth_request e Caddy forward_auth fazem verificações GET. Por isso, as exclusões específicas por método precisam de encaminhamento separado no reverse proxy nessas configurações. Cada entrada cria uma abertura no controlo de acesso. Por isso, ancore as expressões com ^ e mantenha-as tão restritas quanto o chamador permitir.

Execute a versão v7.15.5 ou posterior antes de depender destas opções. Versões anteriores posteriores à v7.5.0 podiam ser induzidas a excluir um caminho protegido através de um pedido que usasse segmentos de caminho com ponto, uma barra inicial duplicada ou um ponto e vírgula (aviso GHSA-63jm-59jj-478j). Ancorar as expressões não impedia o problema. A versão corrigida recusa excluir esses caminhos ambíguos. Depois da atualização, confirme que as suas rotas públicas continuam a corresponder.

Websockets são o caso que costuma ser configurado incorretamente. O pedido de upgrade é um GET HTTP normal que transporta os mesmos cookies que qualquer outro pedido. Por isso, passa normalmente pela verificação e não precisa de exclusão. O problema está no encaminhamento associado. Sem os cabeçalhos Upgrade e Connection na localização protegida, o upgrade não termina e o cliente da aplicação tenta novamente indefinidamente, apresentando uma mensagem WebSocket connection ... failed na consola do navegador. Excluir o caminho não resolve o problema, porque o pedido já tinha sido autorizado.

Existe uma limitação real. A verificação é executada uma vez, no upgrade. Um websocket que permaneça aberto durante horas nunca volta a ser verificado. Por isso, remover um utilizador do provider não fecha o socket que ele já tem aberto. Reinicie a aplicação para terminar as ligações ativas.

Por predefinição, a sessão inteira fica dentro do cookie, encriptada com o seu cookie_secret. Isto mantém o oauth2-proxy sem estado e não exige um serviço adicional. Também existe um limite, porque os navegadores restringem um cookie a cerca de 4 KB. Quando o token de ID contém uma lista longa de claims de grupos, o oauth2-proxy divide a sessão entre _oauth2_proxy_0, _oauth2_proxy_1 e os seguintes. Depois de algumas partes, os cabeçalhos do pedido ficam suficientemente grandes para que o nginx responda com 400 Request Header Or Cookie Too Large antes de a aplicação sequer receber o pedido.

Quando isso acontecer, mova a sessão para o servidor:

session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"

O navegador passa a guardar um ticket curto, enquanto a sessão encriptada fica no Redis. O custo é um serviço que tem de permanecer ativo: se o Redis ficar indisponível, o oauth2-proxy não consegue carregar as sessões; se os dados de sessão armazenados forem perdidos, todos terão de iniciar sessão novamente. O armazenamento em cookies também tem um custo: dois pedidos que atualizem a mesma sessão ao mesmo tempo podem entrar em conflito e obrigar a iniciar sessão novamente.

O que a autenticação externa não oferece

Isto é uma barreira na entrada. Não é autorização dentro da aplicação, e essa diferença determina se a abordagem é adequada ao seu caso.

Depois de um utilizador passar, a aplicação vê o mesmo que via antes. Se a aplicação tiver funções próprias, a autenticação externa não as preenche, exceto se a aplicação suportar autenticação baseada em cabeçalhos e mapear um cabeçalho para uma conta. O Grafana faz isso através das definições auth.proxy. A maioria das aplicações autoalojadas não faz, por isso todos os utilizadores que passam pela barreira representam a mesma identidade única para a aplicação, e essa identidade é frequentemente uma conta de administrador.

Isto também não protege os tokens de API da própria aplicação. Um token de acesso pessoal emitido pela aplicação autentica-se na aplicação, não no oauth2-proxy, por isso o token deixa de funcionar assim que a barreira é colocada à frente dele. Exclua o caminho da API para o reativar, e esse token passa a ser a única proteção do caminho. Terá agora dois sistemas de autenticação num único serviço, e o SSO cobre apenas um deles.

A revogação é a terceira limitação. Eliminar um utilizador no seu fornecedor impede novos logins, mas o oauth2-proxy não verifica uma sessão existente com o fornecedor até cookie_refresh ser atingido. Com a renovação desativada, o cookie da sessão continua válido até expirar, e cookie_expire tem o valor predefinido de 168 horas, o que pode representar uma semana de acesso para alguém que acabou de remover. Defina cookie_refresh para um valor curto, como uma hora. Quando o fornecedor rejeitar essa renovação porque o token de renovação do utilizador já não é válido, o oauth2-proxy elimina a sessão e força um novo login no próximo pedido que tentar fazer a renovação. Nem todos os fornecedores suportam renovação, por isso teste-a com o seu fornecedor.

O registo de auditoria também termina na barreira. O oauth2-proxy regista quem passou e quando. A aplicação regista uma sessão sem nome. Se tiver de responder a quem alterou uma definição, a identidade através de cabeçalhos na aplicação é o mínimo necessário, e contas reais por utilizador são a resposta correta.

Pagar pelo SSO é a melhor opção

A autenticação externa é a ferramenta certa quando uma aplicação não tem qualquer início de sessão ou usa uma única palavra-passe partilhada, e pretende ter um único local para adicionar e remover utilizadores. A configuração demora uma tarde e acrescenta apenas um processo. Funciona com qualquer aplicação que comunique por HTTP.

É a ferramenta errada quando pessoas diferentes precisam de permissões diferentes dentro da mesma aplicação. Uma barreira não consegue expressar que “Ana pode editar os dashboards e Bo só os pode ler”. Se o fornecedor vender um nível de serviço com SSO, o mapeamento entre grupos e funções é normalmente aquilo que está realmente a comprar. Recriá-lo com cabeçalhos e regras do proxy é mais frágil do que pagar por essa funcionalidade. O padrão de preços por trás desses níveis de SSO merece ser lido antes de decidir.

Qualquer aplicação com um cliente móvel ou de desktop que não transporte cookies do navegador terá problemas com a barreira em todos os pedidos.

FAQ

O que é forward auth?

Forward auth é um padrão no qual o reverse proxy consulta um serviço de autenticação separado para cada pedido recebido antes de o encaminhar para o upstream. O proxy envia os cabeçalhos do pedido para um endpoint como /oauth2/auth e lê o código de estado. 202 significa que o pedido foi permitido, portanto o pedido original é encaminhado para a aplicação. 401 significa que não existe uma sessão válida, portanto o proxy redireciona o browser para a página de login. O Nginx implementa esta funcionalidade com a diretiva auth_request, o Traefik com o middleware forwardAuth e o Caddy com forward_auth.

Por que o oauth2-proxy me redireciona de volta para a página de login num ciclo?

O cookie de sessão está ausente ou falha na validação, portanto cada verificação não encontra uma sessão válida e redireciona-o de volta para o login. Instâncias que usam segredos de cookie diferentes rejeitam os cookies umas das outras. Outra causa é cookie_secure = true num site que o browser acedeu através de HTTP simples, porque, exceto em localhost, um browser não armazena um cookie Secure numa origem http://. Verifique também se existe um valor cookie_domains que não abrange o hostname apresentado na barra de endereço. Leia o cabeçalho Set-Cookie na resposta /oauth2/callback através das ferramentas de desenvolvimento do browser para descobrir qual cookie está ausente. Se o cookie for devolvido, verifique o log do servidor à procura de erros de validação. Se o cookie CSRF estiver ausente, será apresentada uma página 403 com Login Failed: Unable to find a valid CSRF token. Please try again. em vez de um ciclo, e o log apresentará No cookies were found in OAuth callback. quando não forem recebidos cookies.

Como permito que um cliente de API ou um webhook passe pelo oauth2-proxy?

Use skip_auth_routes com uma expressão regular ancorada, opcionalmente limitada a um método HTTP, por exemplo POST=^/webhook/, e execute a versão v7.15.5 ou posterior, que corrigiu um bypass crítico destas exceções. As exceções específicas por método exigem que o pedido de autenticação preserve o método original; os exemplos para nginx e Caddy fazem verificações GET, portanto trate essas exceções no encaminhamento do reverse proxy. Se os seus clientes de API já tiverem JWTs válidos emitidos pelo provider configurado, com uma audience aceite, skip_jwt_bearer_tokens = true aceita esses tokens em vez de um cookie e mantém o caminho protegido. A audience tem de corresponder a client_id ou a uma audience configurada através de extra_jwt_issuers. Tudo o que estiver listado em skip_auth_routes fica sem autenticação para todos, portanto mantenha cada expressão tão restrita quanto o cliente permitir.

O oauth2-proxy fornece permissões por utilizador à aplicação?

Não. É uma barreira de acesso, não um sistema de autorização. Decide quem chega à aplicação, e todas as pessoas que chegam parecem idênticas para a aplicação, a menos que esta leia os cabeçalhos de identidade e os associe a contas. O Grafana pode fazer isto através das definições auth.proxy. A maioria das aplicações self-hosted não consegue fazê-lo, portanto todas as pessoas que passam a barreira partilham a mesma identidade com que a aplicação está a ser executada.

É possível contornar o oauth2-proxy definindo diretamente o cabeçalho de identidade?

Sim, se for possível aceder diretamente à aplicação. A identidade chega como um cabeçalho simples, como X-Auth-Request-Email, e a aplicação confia no que receber. Qualquer pessoa que consiga abrir uma ligação à porta da aplicação pode enviar esse cabeçalho e assumir a identidade de qualquer utilizador. Ligue a aplicação a 127.0.0.1 ou mantenha-a numa rede Docker interna sem uma porta publicada, e confirme essa configuração com sudo ss -tlnp.

Este artigo foi útil?

#oauth2-proxy#sso#oidc#reverse-proxy#forward-auth