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

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

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

​

Cabeçalho de escopos do operador

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

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

​

Terminação TLS e HSTS

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

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

​

Lista de verificação de segurança

• 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

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

​

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