{"id":613,"date":"2026-03-21T22:52:56","date_gmt":"2026-03-21T14:52:56","guid":{"rendered":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/gateway-trusted-proxy-auth\/"},"modified":"2026-03-21T23:28:51","modified_gmt":"2026-03-21T15:28:51","slug":"gateway-trusted-proxy-auth","status":"publish","type":"post","link":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/gateway-trusted-proxy-auth\/","title":{"rendered":"Trusted Proxy Auth"},"content":{"rendered":"

Trusted Proxy Auth<\/h1>\n
\n

\u26a0\ufe0f Security-sensitive feature.<\/strong> This mode delegates authentication entirely to your reverse proxy. Misconfiguration can expose your Gateway \u7f51\u5173 to unauthorized access. Read this page carefully before enabling.<\/p>\n<\/blockquote>\n

When to Use<\/h2>\n

Use trusted-proxy<\/code> auth mode when:<\/p>\n

    \n
  • You run OpenClaw behind an identity-aware proxy<\/strong> (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)<\/li>\n
  • Your proxy handles all authentication and passes user identity via headers<\/li>\n
  • You’re in a Kubernetes or container environment where the proxy is the only path to the Gateway \u7f51\u5173<\/li>\n
  • You’re hitting WebSocket 1008 unauthorized<\/code> errors because browsers can’t pass tokens in WS payloads<\/li>\n<\/ul>\n

    When NOT to Use<\/h2>\n
      \n
    • If your proxy doesn’t authenticate users (just a TLS terminator or load balancer)<\/li>\n
    • If there’s any path to the Gateway \u7f51\u5173 that bypasses the proxy (firewall holes, internal network access)<\/li>\n
    • If you’re unsure whether your proxy correctly strips\/overwrites forwarded headers<\/li>\n
    • If you only need personal single-user access (consider Tailscale Serve + loopback for simpler setup)<\/li>\n<\/ul>\n

      How It Works<\/h2>\n
        \n
      1. Your reverse proxy authenticates users (OAuth, OIDC, SAML, etc.)<\/li>\n
      2. Proxy adds a header with the authenticated user identity (e.g., x-forwarded-user: nick@example.com<\/code>)<\/li>\n
      3. OpenClaw checks that the request came from a trusted proxy IP<\/strong> (configured in gateway.trustedProxies<\/code>)<\/li>\n
      4. OpenClaw extracts the user identity from the configured header<\/li>\n
      5. If everything checks out, the request is authorized<\/li>\n<\/ol>\n

        Control UI Pairing Behavior<\/h2>\n

        When gateway.auth.mode = \"trusted-proxy\"<\/code> is active and the request passes
        \ntrusted-proxy checks, Control UI WebSocket sessions can connect without device
        \npairing identity.<\/p>\n

        Implications:<\/p>\n

          \n
        • Pairing is no longer the primary gate for Control UI access in this mode.<\/li>\n
        • Your reverse proxy auth policy and allowUsers<\/code> become the effective access control.<\/li>\n
        • Keep \u7f51\u5173 ingress locked to trusted proxy IPs only (gateway.trustedProxies<\/code> + firewall).<\/li>\n<\/ul>\n

          \u914d\u7f6e\u8bf4\u660e<\/h2>\n

          “`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
          \n{
          \n \u7f51\u5173: {
          \n \/\/ Use loopback for same-host proxy setups; use lan\/custom for remote proxy hosts
          \n bind: “loopback”,<\/p>\n

          \/\/ CRITICAL: Only add your proxy's IP(s) here\ntrustedProxies: [\"10.0.0.1\", \"172.17.0.1\"],\n\nauth: {\n  mode: \"trusted-proxy\",\n  trustedProxy: {\n    \/\/ Header containing authenticated user identity (required)\n    userHeader: \"x-forwarded-user\",\n\n    \/\/ Optional: headers that MUST be present (proxy verification)\n    requiredHeaders: [\"x-forwarded-proto\", \"x-forwarded-host\"],\n\n    \/\/ Optional: restrict to specific users (empty = allow all)\n    allowUsers: [\"nick@example.com\", \"admin@company.org\"],\n  },\n},\n<\/code><\/pre>\n
          },
          \n}<\/p>\n
          \nIf `gateway.bind` is `loopback`, include a loopback proxy address in\n`gateway.trustedProxies` (`127.0.0.1`, `::1`, or an equivalent loopback CIDR).\n\n### Configuration Reference\n\n| Field                                       | Required | Description                                                                 |\n| ------------------------------------------- | -------- | --------------------------------------------------------------------------- |\n| `gateway.trustedProxies`                    | Yes      | Array of proxy IP addresses to trust. Requests from other IPs are rejected. |\n| `gateway.auth.mode`                         | Yes      | Must be `"trusted-proxy"`                                                   |\n| `gateway.auth.trustedProxy.userHeader`      | Yes      | Header name containing the authenticated user identity                      |\n| `gateway.auth.trustedProxy.requiredHeaders` | No       | Additional headers that must be present for the request to be trusted       |\n| `gateway.auth.trustedProxy.allowUsers`      | No       | Allowlist of user identities. Empty means allow all authenticated users.    |\n\n## TLS termination and HSTS\n\nUse one TLS termination point and apply HSTS there.\n\n### Recommended pattern: proxy TLS termination\n\nWhen your reverse proxy handles HTTPS for `https:\/\/control.example.com`, set\n`Strict-Transport-Security` at the proxy for that domain.\n\n* Good fit for internet-facing deployments.\n* Keeps certificate + HTTP hardening policy in one place.\n* OpenClaw can stay on loopback HTTP behind the proxy.\n\nExample header value:\n\n```text  theme={"theme":{"light":"min-light","dark":"min-dark"}}\nStrict-Transport-Security: max-age=31536000; includeSubDomains\n<\/code><\/pre>\n
          Gateway \u7f51\u5173 TLS termination<\/h3>\n
          If OpenClaw itself serves HTTPS directly (no TLS-terminating proxy), set:<\/p>\n
          “`json5  theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
          \n{
          \n  \u7f51\u5173: {
          \n    tls: { enabled: true },
          \n    http: {
          \n      securityHeaders: {
          \n        strictTransportSecurity: “max-age=31536000; includeSubDomains”,
          \n      },
          \n    },
          \n  },
          \n}<\/p>\n
          \n`strictTransportSecurity` accepts a string header value, or `false` to disable explicitly.\n\n### Rollout guidance\n\n* Start with a short max age first (for example `max-age=300`) while validating traffic.\n* Increase to long-lived values (for example `max-age=31536000`) only after confidence is high.\n* Add `includeSubDomains` only if every subdomain is HTTPS-ready.\n* Use preload only if you intentionally meet preload requirements for your full domain set.\n* Loopback-only local development does not benefit from HSTS.\n\n## Proxy Setup Examples\n\n### Pomerium\n\nPomerium passes identity in `x-pomerium-claim-email` (or other claim headers) and a JWT in `x-pomerium-jwt-assertion`.\n\n```json5  theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n  gateway: {\n    bind: "lan",\n    trustedProxies: ["10.0.0.1"], \/\/ Pomerium's IP\n    auth: {\n      mode: "trusted-proxy",\n      trustedProxy: {\n        userHeader: "x-pomerium-claim-email",\n        requiredHeaders: ["x-pomerium-jwt-assertion"],\n      },\n    },\n  },\n}\n<\/code><\/pre>\n
          Pomerium config snippet:<\/p>\n
          “`yaml  theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
          \nroutes:
          \n  – from: https:\/\/openclaw.example.com
          \n    to: http:\/\/openclaw-\u7f51\u5173:18789
          \n    policy:
          \n      – allow:
          \n          or:
          \n            – email:
          \n                is: nick@example.com
          \n    pass_identity_headers: true<\/p>\n
          \n### Caddy with OAuth\n\nCaddy with the `caddy-security` plugin can authenticate users and pass identity headers.\n\n```json5  theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n  gateway: {\n    bind: "lan",\n    trustedProxies: ["127.0.0.1"], \/\/ Caddy's IP (if on same host)\n    auth: {\n      mode: "trusted-proxy",\n      trustedProxy: {\n        userHeader: "x-forwarded-user",\n      },\n    },\n  },\n}\n<\/code><\/pre>\n
          Caddyfile snippet:<\/p>\n
          openclaw.example.com {\n    authenticate with oauth2_provider\n    authorize with policy1\n\n    reverse_proxy openclaw:18789 {\n        header_up X-Forwarded-User {http.auth.user.email}\n    }\n}\n<\/code><\/pre>\n
          nginx + oauth2-proxy<\/h3>\n
          oauth2-proxy authenticates users and passes identity in x-auth-request-email<\/code>.<\/p>\n
          “`json5  theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
          \n{
          \n  \u7f51\u5173: {
          \n    bind: “lan”,
          \n    trustedProxies: [“10.0.0.1”], \/\/ nginx\/oauth2-proxy IP
          \n    auth: {
          \n      mode: “trusted-proxy”,
          \n      trustedProxy: {
          \n        userHeader: “x-auth-request-email”,
          \n      },
          \n    },
          \n  },
          \n}<\/p>\n
          \nnginx config snippet:\n\n```nginx  theme={"theme":{"light":"min-light","dark":"min-dark"}}\nlocation \/ {\n    auth_request \/oauth2\/auth;\n    auth_request_set $user $upstream_http_x_auth_request_email;\n\n    proxy_pass http:\/\/openclaw:18789;\n    proxy_set_header X-Auth-Request-Email $user;\n    proxy_http_version 1.1;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection "upgrade";\n}\n<\/code><\/pre>\n
          Traefik with Forward Auth<\/h3>\n
          json5  theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
          \n{
          \n  gateway: {
          \n    bind: \"lan\",
          \n    trustedProxies: [\"172.17.0.1\"], \/\/ Traefik container IP
          \n    auth: {
          \n      mode: \"trusted-proxy\",
          \n      trustedProxy: {
          \n        userHeader: \"x-forwarded-user\",
          \n      },
          \n    },
          \n  },
          \n}<\/code><\/p>\n
          Security Checklist<\/h2>\n
          Before enabling trusted-proxy auth, verify:<\/p>\n