Gateway Trusted Proxy 认证

将 Gateway 认证委托给受信反向代理（Pomerium、Caddy、nginx + OAuth）。安全敏感功能，配置错误会导致未授权访问。

适用场景

• 运行在身份感知代理（Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik）后面
• 代理处理所有认证并通过 header 传递用户身份
• Kubernetes/容器环境中代理是唯一入口
• 浏览器无法在 WS payload 中传 token 导致 1008 unauthorized

不适用场景

• 代理只做 TLS 终止，不认证用户
• 存在绕过代理直接访问 Gateway 的路径
• 不确定代理是否正确剥离/覆盖转发 header

工作原理

1. 代理认证用户（OAuth/OIDC/SAML）
2. 代理添加身份 header（如 x-forwarded-user: nick@example.com）
3. Gateway 验证请求来自受信代理 IP（gateway.trustedProxies）
4. Gateway 从 header 提取用户身份
5. 授权通过

配置示例

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1", "172.17.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],
        allowUsers: ["nick@example.com", "admin@company.org"],
        allowLoopback: false,
      },
    },
  },
}

重要：默认拒绝 loopback 来源请求。同主机 loopback 代理需显式设置 allowLoopback: true。

代理示例

Pomerium：userHeader: "x-pomerium-claim-email"，requiredHeaders: ["x-pomerium-jwt-assertion"]

nginx + oauth2-proxy：userHeader: "x-auth-request-email"

Caddy：userHeader: "x-forwarded-user"

Operator Scopes Header

trusted-proxy 模式支持 x-openclaw-scopes header 声明权限：

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

header 缺失时回退到默认 operator scope 集合。

安全检查清单

• 代理是唯一入口，Gateway 端口已防火墙隔离
• trustedProxies 只包含实际代理 IP
• 代理会覆盖（非追加）x-forwarded-* header
• 代理处理 TLS，用户通过 HTTPS 连接
• 不同时设置 gateway.auth.token 和 trusted-proxy 模式

相关

• gateway-authentication
• gateway-tailscale