Autenticação por proxy confiável do OpenClaw

A autenticação por proxy confiável é o modo para gateways que ficam atrás de um proxy com reconhecimento de identidade: o proxy autentica a pessoa, adiciona um cabeçalho com a identidade dela e o gateway confia nesse cabeçalho, mas só quando ele vem do proxy. A documentação abre com um aviso de que uma configuração errada expõe o gateway, e a maior parte da página é a lista de verificações que tornam essa confiança segura. Aqui está ela, na ordem em que o gateway a avalia.

Quando e como

• Use-o atrás do Pomerium, do Caddy com OAuth, do nginx com oauth2-proxy ou do Traefik com forward auth, em ambientes de contêineres onde o proxy é o único caminho, ou quando os navegadores recebem erros de WebSocket não autorizado porque não conseguem passar tokens no handshake; não o use quando o proxy só termina o TLS, quando algum caminho contorna o proxy, quando você não tem certeza de que o proxy remove os cabeçalhos encaminhados, ou para acesso pessoal de um único usuário, em que uma tailnet mais loopback é mais simples.
• O fluxo: o proxy autentica o usuário, adiciona um cabeçalho de identidade, como o cabeçalho de usuário encaminhado, o gateway verifica se a requisição veio de um endereço de proxy confiável, lê os cabeçalhos obrigatórios e a identidade do usuário, e autoriza quando a lista de permissões de usuários, se definida, inclui o usuário; a configuração se vincula à rede local, lista apenas os endereços ou faixas do proxy, define o modo de autenticação, o cabeçalho de usuário, cabeçalhos obrigatórios opcionais, uma lista de permissões de usuários opcional, o loopback desativado por padrão e a aprovação automática de dispositivos desativada por padrão.
• Regras de execução em ordem: o tráfego com formato de proxy é atribuído antes da autenticação do gateway e precisa vir de um proxy confiável com cabeçalhos de endereço do cliente que resolvam para um cliente fora do loopback, ou as rotas autenticadas pelo gateway o rejeitam por falta de atribuição de proxy; o proxy precisa sobrescrever a cadeia de forwarded-for com segurança, e o cabeçalho de endereço real só é aceito quando o fallback dele está ativado; origens de loopback são rejeitadas a menos que a opção esteja em true e o loopback também esteja listado como proxy confiável; origens que coincidem com um dos endereços das interfaces do próprio host são rejeitadas como proteção contra spoofing, e uma descoberta de interfaces que falha também rejeita; depois, os cabeçalhos obrigatórios e o cabeçalho de usuário precisam estar presentes e não vazios, e a lista de permissões de usuários precisa incluir o usuário.
• Evidências de cabeçalhos encaminhados em uma requisição de loopback a desqualificam do fallback de senha local direto e do controle por identidade de dispositivo, e ela continua falhando na autenticação por proxy confiável; clientes internos que não passam pelo proxy usam a senha do gateway, que o comando status seleciona automaticamente quando não há uma URL sobrescrita; a lista de proxies confiáveis aceita faixas de endereços na forma simples ou mapeada, e um prefixo mapeado que cobre tudo ainda precisa da opção de loopback para aceitar o loopback.

Um token do Gateway não pode substituir a autenticação pelo proxy.

Concessões, aprovação automática e o cabeçalho de escopos

Os escopos por identidade dão a usuários verificados selecionados escopos válidos só para a sessão, sem ampliar a concessão do dispositivo deles: a chave é a identidade do proxy ou o login da tailnet, os e-mails são comparados sem diferenciar maiúsculas de minúsculas, a concessão é unida aos escopos autorizados do dispositivo e depois limitada por um cabeçalho de escopos explícito, e conexões por token, por senha e sem autenticação nunca recebem uma. A aprovação automática de dispositivos, desativada por padrão, usa a identidade do proxy como fronteira de aprovação para novos dispositivos de operador, sejam de navegador ou nativos,, e para upgrades de escopo com a mesma chave: só se qualificam conexões via proxy confiável com uma identidade não vazia que passou pela lista de permissões, conexões com papel de nó e upgrades de papel nunca se qualificam, os escopos solicitados são intersectados com a lista configurada (read, write, approvals e questions quando ela não está definida, nunca ampliada), o cabeçalho de escopos do proxy também limita a concessão persistente, e incluir admin na lista permite que todo usuário do proxy receba um dispositivo com admin completo, o que a auditoria de segurança reporta como crítico e sobre o que o gateway avisa na inicialização. Sessões da interface de controle sem dispositivo não podem declarar os próprios escopos: a lista delas é esvaziada e uma concessão por identidade correspondente é aplicada; uma falha de escopo ausente depois de uma conexão bem-sucedida significa que é preciso recarregar para que o navegador pareie a identidade do dispositivo. O cabeçalho de escopos declara escopos quando está presente, não declara nenhum quando está presente mas vazio, e volta ao conjunto padrão de operador quando está ausente, enquanto as rotas de plugin autenticadas pelo gateway voltam apenas a write.

TLS, tokens mistos e a auditoria

• Termine o TLS uma única vez e defina o cabeçalho de strict transport nesse ponto: no proxy, para implantações expostas à internet com o gateway em loopback atrás dele, ou no gateway, com TLS ativado e o cabeçalho de strict transport security, quando ele mesmo serve HTTPS; comece com um max age curto, aumente-o só quando tiver confiança, adicione a flag de subdomínios só quando todos os subdomínios estiverem prontos, e dispense-o no desenvolvimento só em loopback.
• A inicialização rejeita a autenticação por proxy confiável quando um token compartilhado também está configurado, porque um token permitiria que chamadores no mesmo host se autenticassem por um caminho diferente da identidade verificada pelo proxy; remova o token ou troque o modo, e lembre-se de que cabeçalhos de identidade vindos de loopback continuam falhando fechados e que o fallback por token não é suportado de propósito.
• A auditoria de segurança sinaliza o modo como crítico por design e verifica se falta a lista de proxies confiáveis, se falta o cabeçalho de usuário, se a lista de permissões de usuários está vazia, se a opção de loopback está ativada e se a aprovação automática de dispositivos está ativada; o checklist acrescenta que o proxy seja o único caminho, que a lista de confiáveis seja mínima, que o proxy sobrescreva os cabeçalhos encaminhados e reconstrua a cadeia de forwarded-for, que as origens permitidas sejam explícitas para uma interface de controle fora do loopback, e que qualquer fallback de senha local fique privado atrás do firewall.

O guia de escopos de operador do OpenClaw explica o modelo de escopos que essas concessões alimentam, e o OpenClaw no Tailscale, a alternativa mais simples para acesso restrito à tailnet.

Como ler os códigos de rejeição

A seção de solução de problemas mapeia cada rejeição: uma origem não confiável significa que a requisição não veio de um endereço de proxy listado, o que muda quando os contêineres reiniciam; uma origem de loopback significa um proxy no mesmo host sem a opção deliberada; uma origem de interface local significa que um processo no host do gateway está enviando cabeçalhos de identidade diretamente ou que o proxy compartilha o namespace de rede do host; um usuário ausente significa que o cabeçalho está ausente ou com o nome errado; um usuário não permitido significa que a conta está autenticada, mas não está na lista de permissões, e a documentação diz para não remover a lista de permissões como paliativo; uma origem não permitida significa que a origem do navegador falhou na verificação da interface de controle. A mensagem dizendo que a autenticação por proxy é obrigatória indica uma identidade rejeitada, não uma queda de rede, e a correção é entrar pelo proxy em vez de enviar cabeçalhos pelo navegador. A migração da autenticação por token tem seis etapas: configurar o proxy, testá-lo de forma independente, atualizar a configuração do gateway, reiniciar, testar o WebSocket pela interface de controle e executar a auditoria. O acesso remoto do OpenClaw compara os outros padrões de acesso remoto, e o pareamento do OpenClaw, o fluxo de dispositivos que a aprovação automática substitui.

Na Diali

Na Diali, cada gateway de cliente é acessado pelo ingress da plataforma, com a configuração do motor gerada a partir do painel e substituída a cada versão, então esse modo não é algo que um cliente precise montar à mão. O OpenClaw hospedado na Diali descreve o assistente hospedado, e a segurança da Diali, a fronteira em torno de cada motor.

• Confie no cabeçalho só quando ele vier de endereços de proxy listados.
• Origens de loopback e das próprias interfaces falham fechadas.
• O cabeçalho de escopos restringe; as concessões por identidade adicionam, só para a sessão.