Autenticação por proxy confiável

# Quando usar

Use o modo de autenticação trusted-proxy quando:

• Você executa o OpenClaw atrás de um proxy ciente de identidade (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Seu proxy lida com toda a autenticação e passa a identidade do usuário por meio de cabeçalhos.
• Você está em um ambiente Kubernetes ou de contêiner em que o proxy é o único caminho até o Gateway.
• Você está encontrando erros WebSocket 1008 unauthorized porque navegadores não conseguem passar tokens em payloads WS.

# Quando NÃO usar

• Se seu proxy não autentica usuários (apenas um terminador TLS ou balanceador de carga).
• Se houver qualquer caminho até o Gateway que contorne o proxy (brechas no firewall, acesso pela rede interna).
• Se você não tiver certeza de que seu proxy remove/substitui corretamente os cabeçalhos encaminhados.
• Se você só precisa de acesso pessoal de usuário único (considere Tailscale Serve + loopback para uma configuração mais simples).

# Como funciona

# Comportamento de pareamento da Control UI

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

Implicações:

• O pareamento deixa de ser a barreira principal para acesso à Control UI neste modo.
• A política de autenticação do seu proxy reverso e allowUsers se tornam o controle de acesso efetivo.
• Mantenha a entrada do gateway bloqueada apenas para IPs de proxy confiáveis (gateway.trustedProxies + firewall).

# Configuração

{
  gateway: {
    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default
    bind: "lan",

    // CRITICAL: Only add your proxy's IP(s) here
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Header containing authenticated user identity (required)
        userHeader: "x-forwarded-user",

        // Optional: headers that MUST be present (proxy verification)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Optional: restrict to specific users (empty = allow all)
        allowUsers: ["[email protected]", "[email protected]"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

# Referência de configuração

# Terminação TLS e HSTS

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

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

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

# Orientação de implantação gradual

• Comece primeiro com uma duração 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 ter alta confiança.
• Adicione includeSubDomains somente se todos os subdomínios estiverem prontos para HTTPS.
• Use preload somente se você atender intencionalmente aos requisitos de preload para todo o conjunto de domínios.
• O desenvolvimento local apenas em loopback não se beneficia de HSTS.

# Exemplos de configuração de proxy

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomerium's IP
    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: [email protected]
    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

O OpenClaw rejeita configurações ambíguas em que tanto um gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN) quanto o modo trusted-proxy estão ativos ao mesmo tempo. Configurações mistas de token podem fazer com que solicitações de loopback sejam autenticadas silenciosamente pelo caminho de autenticação errado.

Se você vir um erro mixed_trusted_proxy_token na inicialização:

• Remova o token compartilhado ao usar o modo trusted-proxy, ou
• Altere gateway.auth.mode para "token" se você pretende usar autenticação baseada em token.

Cabeçalhos de identidade trusted-proxy em loopback ainda falham de forma fechada: chamadores no mesmo host não são autenticados silenciosamente como usuários de proxy. Chamadores internos do OpenClaw que contornam o proxy podem se autenticar com gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD em vez disso. O fallback por token continua intencionalmente sem suporte no modo trusted-proxy.

# Cabeçalho de escopos de operador

A autenticação trusted-proxy é um modo HTTP portador de identidade, então os chamadores podem declarar opcionalmente escopos de operador com x-openclaw-scopes.

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, APIs HTTP portadoras de identidade normais recorrem ao conjunto padrão de escopos de operador.
• As rotas HTTP de Plugin com autenticação de Gateway são mais restritas por padrão: quando x-openclaw-scopes está ausente, o escopo de runtime delas recorre a operator.write.
• Solicitações HTTP de origem em navegador ainda precisam passar por gateway.controlUi.allowedOrigins (ou modo deliberado de fallback por cabeçalho Host) mesmo depois que a autenticação trusted-proxy é bem-sucedida.

Regra prática: envie x-openclaw-scopes explicitamente quando quiser que uma solicitação trusted-proxy seja mais restrita do que os padrões, ou quando uma rota de Plugin com autenticação de gateway precisar de algo mais forte do que escopo de escrita.

# Lista de verificação de segurança

Antes de habilitar a autenticação trusted-proxy, verifique:

• [ ] O proxy é o único caminho: A porta do Gateway está protegida por firewall de tudo, exceto seu proxy.
• [ ] trustedProxies é mínimo: Somente os IPs reais do seu proxy, não sub-redes inteiras.
• [ ] A origem de proxy em loopback é deliberada: A autenticação trusted-proxy falha de forma fechada para solicitações com origem em loopback, a menos que gateway.auth.trustedProxy.allowLoopback esteja explicitamente habilitado para um proxy no mesmo host.
• [ ] O proxy remove cabeçalhos: Seu proxy sobrescreve (não acrescenta) cabeçalhos x-forwarded-* dos clientes.
• [ ] Terminação TLS: Seu proxy lida com TLS; usuários se conectam via HTTPS.
• [ ] allowedOrigins é explícito: A UI de Controle não loopback usa gateway.controlUi.allowedOrigins explícito.
• [ ] allowUsers está definido (recomendado): Restrinja a usuários conhecidos em vez de permitir qualquer pessoa autenticada.
• [ ] Nenhuma configuração mista de token: Não defina gateway.auth.token e gateway.auth.mode: "trusted-proxy" ao mesmo tempo.
• [ ] O fallback de senha local é privado: Se você configurar gateway.auth.password para chamadores diretos internos, 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 sinalizará a autenticação trusted-proxy com uma descoberta de severidade crítica. Isso é intencional — é um lembrete de que você está delegando a segurança à configuração do seu proxy.

A auditoria verifica:

• Aviso/lembrete crítico base gateway.trusted_proxy_auth
• Configuração trustedProxies ausente
• Configuração userHeader ausente
• allowUsers vazio (permite qualquer usuário autenticado)
• allowLoopback habilitado para origens de proxy no mesmo host
• Política de origem do navegador curinga ou ausente em superfícies expostas da UI de Controle

# Solução de problemas

# Migração da autenticação por token

Se você está migrando da autenticação por token para trusted-proxy:

# Relacionados

• Configuração — referência de configuração
• Acesso remoto — outros padrões de acesso remoto
• Segurança — guia completo de segurança
• Tailscale — alternativa mais simples para acesso somente por tailnet