Autenticação por proxy confiável

Quando usar

• Você executa o OpenClaw por trás de um proxy com reconhecimento de identidade (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + autenticação encaminhada).
• Seu proxy gerencia toda a autenticação e transmite a identidade do usuário por meio de cabeçalhos.
• Você está em um ambiente Kubernetes ou de contêineres no qual o proxy é o único caminho até o Gateway.
• Você está recebendo erros de WebSocket 1008 unauthorized porque os navegadores não conseguem transmitir tokens nas cargas úteis do WS.

Quando NÃO usar

• Seu proxy não autentica usuários (é apenas um terminador TLS ou balanceador de carga).
• Existe algum caminho até o Gateway que contorne o proxy (brechas no firewall, acesso pela rede interna).
• Você não tem certeza se o proxy remove ou sobrescreve corretamente os cabeçalhos encaminhados.
• Você precisa apenas de acesso pessoal para um único usuário (considere usar Tailscale Serve + local loopback).

Como funciona

Configuração

{  gateway: {    // Por padrão, a autenticação por proxy confiável espera que o IP de origem do proxy não seja de loopback    bind: "lan",     // CRÍTICO: adicione aqui somente os IPs do seu proxy    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Cabeçalho que contém a identidade do usuário autenticado (obrigatório)        userHeader: "x-forwarded-user",         // Opcional: cabeçalhos que DEVEM estar presentes (verificação do proxy)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Opcional: restringe a usuários específicos (vazio = permite todos)        allowUsers: ["nick@example.com", "admin@company.org"],         // Opcional: permite um proxy de loopback no mesmo host após adesão explícita        allowLoopback: false,      },    },  },}

Referência de configuração

Comportamento de pareamento da UI de Controle

Quando gateway.auth.mode = "trusted-proxy" está ativo e a solicitação passa pelas verificações de proxy confiável, as sessões WebSocket da UI de Controle podem se conectar sem uma identidade de pareamento de dispositivo.

Implicações de escopo:

• As sessões WebSocket da UI de Controle sem dispositivo se conectam, mas não recebem nenhum escopo de operador por padrão. O OpenClaw limpa a lista de escopos solicitados para [], impedindo que uma sessão não vinculada a um dispositivo/token pareado e aprovado declare permissões para si mesma.
• Se métodos falharem com missing scope após uma conexão WebSocket bem-sucedida, use HTTPS para que o navegador possa gerar uma identidade de dispositivo e concluir o pareamento. Consulte HTTP não seguro da UI de Controle.
• Somente em caso de emergência: gateway.controlUi.dangerouslyDisableDeviceAuth=true preserva os escopos solicitados mesmo sem identidade de dispositivo. Isso reduz gravemente a segurança; reverta rapidamente. Consulte HTTP não seguro da UI de Controle.

Limitação de escopos pelo proxy reverso: se o proxy enviar x-openclaw-scopes na solicitação de upgrade do WebSocket da UI de Controle, o OpenClaw limitará os escopos da sessão à interseção entre os escopos solicitados e os declarados. Esse cabeçalho não concede escopos; ele apenas restringe os escopos que a sessão pode ter.

Implicações:

• O pareamento deixa de ser o controle principal para acesso à UI de Controle neste modo.
• A política de autenticação do proxy reverso e allowUsers tornam-se o controle de acesso efetivo.
• Mantenha a entrada do Gateway restrita somente aos IPs dos proxies confiáveis (gateway.trustedProxies + firewall).

Clientes WebSocket personalizados não são sessões da UI de Controle. gateway.controlUi.dangerouslyDisableDeviceAuth não concede escopos a clientes arbitrários com client.mode: "backend" nem a clientes no formato da CLI. Automações personalizadas devem usar identidade de dispositivo/pareamento, o caminho auxiliar de backend reservado para acesso local direto com client.id: "gateway-client" ou o Plugin de RPC HTTP administrativo quando uma interface HTTP de solicitação/resposta for mais adequada.

Cabeçalho de escopos do operador

A autenticação por proxy confiável é um modo HTTP que carrega identidade; portanto, os chamadores podem, opcionalmente, declarar escopos de operador com x-openclaw-scopes nas solicitações à API HTTP.

Observação: os escopos de WebSocket são determinados pelo handshake do protocolo do Gateway e pela vinculação da identidade do dispositivo. Nas solicitações de upgrade do WebSocket da UI de Controle, x-openclaw-scopes apenas limita os escopos negociados da sessão, não os concede. Consulte Comportamento de pareamento da UI de Controle.

Exemplos:

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

Comportamento:

• Quando o cabeçalho está presente, o OpenClaw respeita o conjunto de escopos declarado.
• Quando o cabeçalho está presente, mas vazio, a solicitação declara nenhum escopo de operador.
• Quando o cabeçalho está ausente, as APIs HTTP normais que carregam identidade usam como fallback o conjunto padrão de escopos do operador (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• As rotas HTTP de Plugins com autenticação pelo Gateway são mais restritas por padrão: quando x-openclaw-scopes está ausente, o escopo de tempo de execução usa como fallback somente operator.write.
• Solicitações HTTP originadas do navegador ainda precisam passar por gateway.controlUi.allowedOrigins (ou pelo modo de fallback deliberado do cabeçalho Host), mesmo após a autenticação por proxy confiável ser bem-sucedida.

Regra prática: envie x-openclaw-scopes explicitamente quando quiser que uma solicitação de proxy confiável seja mais restrita que os padrões ou quando uma rota de Plugin autenticada pelo Gateway precisar de algo mais forte que o escopo de gravação.

Terminação TLS e HSTS

Use um único ponto de terminação TLS e aplique o HSTS nele.

Strict-Transport-Security: max-age=31536000; includeSubDomains

{  gateway: {    tls: { enabled: true },    http: {      securityHeaders: {        strictTransportSecurity: "max-age=31536000; includeSubDomains",      },    },  },}

Orientações para implantação

• Comece com uma idade máxima curta (por exemplo, max-age=300) enquanto valida o tráfego.
• Aumente para valores de longa duração (por exemplo, max-age=31536000) somente depois de obter alta confiança.
• Adicione includeSubDomains somente se todos os subdomínios estiverem preparados para HTTPS.
• Use a pré-carga somente se você atender intencionalmente aos requisitos de pré-carga para todo o conjunto de domínios.
• O desenvolvimento local somente em loopback não se beneficia do HSTS.

Exemplos de configuração de proxy

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP do Pomerium    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-pomerium-claim-email",        requiredHeaders: ["x-pomerium-jwt-assertion"],      },    },  },}

routes:  - from: https://openclaw.example.com    to: http://openclaw-gateway:18789    policy:      - allow:          or:            - email:                is: nick@example.com    pass_identity_headers: true

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Caddy/sidecar proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

openclaw.example.com {    authenticate with oauth2_provider    authorize with policy1     reverse_proxy openclaw:18789 {        header_up X-Forwarded-User {http.auth.user.email}    }}

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-auth-request-email",      },    },  },}

location / {    auth_request /oauth2/auth;    auth_request_set $user $upstream_http_x_auth_request_email;     proxy_pass http://openclaw:18789;    proxy_set_header X-Auth-Request-Email $user;    proxy_http_version 1.1;    proxy_set_header Upgrade $http_upgrade;    proxy_set_header Connection "upgrade";}

{  gateway: {    bind: "lan",    trustedProxies: ["172.17.0.1"], // Traefik container IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

Configuração mista de token

A inicialização do Gateway rejeita a autenticação por proxy confiável se um token compartilhado também estiver configurado (gateway.auth.token ou OPENCLAW_GATEWAY_TOKEN). As duas opções são mutuamente exclusivas, pois um token compartilhado permitiria que chamadores no mesmo host se autenticassem por um caminho totalmente diferente da identidade verificada pelo proxy que este modo deve impor.

Se a inicialização falhar com um erro como gateway auth mode is trusted-proxy, but a shared token is also configured:

• Remova o token compartilhado ao usar o modo de proxy confiável; ou
• Altere gateway.auth.mode para "token" se você pretende usar autenticação baseada em token.

Os cabeçalhos de identidade do proxy confiável em local loopback ainda falham de forma restritiva: chamadores no mesmo host não são autenticados silenciosamente como usuários do proxy. Chamadores internos do OpenClaw que ignoram o proxy podem se autenticar com gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. O fallback para token continua intencionalmente sem suporte no modo de proxy confiável.

Lista de verificação de segurança

Antes de habilitar a autenticação por proxy confiável, verifique:

• [ ] O proxy é o único caminho: a porta do Gateway está protegida por firewall contra tudo, exceto seu proxy.
• [ ] trustedProxies é mínimo: somente os IPs reais do seu proxy, não sub-redes inteiras.
• [ ] A origem local loopback do proxy é intencional: a autenticação por proxy confiável falha de forma restritiva para solicitações originadas de loopback, a menos que gateway.auth.trustedProxy.allowLoopback seja explicitamente habilitado para um proxy no mesmo host.
• [ ] O proxy remove cabeçalhos: seu proxy sobrescreve (não acrescenta) cabeçalhos x-forwarded-* enviados pelos clientes.
• [ ] Encerramento de TLS: seu proxy gerencia o TLS; os usuários se conectam via HTTPS.
• [ ] allowedOrigins é explícito: a Control UI fora de loopback usa gateway.controlUi.allowedOrigins explícito.
• [ ] allowUsers está definido (recomendado): restrinja o acesso a usuários conhecidos, em vez de permitir qualquer pessoa autenticada.
• [ ] Nenhuma configuração mista de token: não defina simultaneamente gateway.auth.token e gateway.auth.mode: "trusted-proxy".
• [ ] O fallback de senha local é privado: se você configurar gateway.auth.password para chamadores internos diretos, mantenha a porta do Gateway protegida por firewall para que clientes remotos que não passam pelo proxy não possam acessá-la diretamente.

Auditoria de segurança

openclaw security audit sinaliza a autenticação por proxy confiável com uma constatação de severidade crítica. Isso é intencional; serve como lembrete de que você está delegando a segurança à configuração do seu proxy.

A auditoria verifica:

• Aviso/lembrete crítico básico de gateway.trusted_proxy_auth.
• Ausência da configuração trustedProxies.
• Ausência da configuração userHeader.
• allowUsers vazio (permite qualquer usuário autenticado).
• allowLoopback habilitado para origens de proxy no mesmo host.

Constatações separadas e não específicas de proxy confiável também se aplicam sempre que a Control UI está exposta: gateway.controlUi.allowedOrigins ausente ou com curinga e fallback de origem baseado no cabeçalho Host.

Solução de problemas

Migração da autenticação por token

Relacionado

• Configuração — referência de configuração
• Escopos do operador — funções, escopos e verificações de aprovação
• Acesso remoto — outros padrões de acesso remoto
• Segurança — guia completo de segurança
• Tailscale — alternativa mais simples para acesso restrito à tailnet