| --- |
| summary: "Delegate gateway authentication to a trusted reverse proxy (Pomerium, Caddy, nginx + OAuth)" |
| read_when: |
| - Running OpenClaw behind an identity-aware proxy |
| - Setting up Pomerium, Caddy, or nginx with OAuth in front of OpenClaw |
| - Fixing WebSocket 1008 unauthorized errors with reverse proxy setups |
| - Deciding where to set HSTS and other HTTP hardening headers |
| --- |
| |
| # Trusted Proxy Auth |
|
|
| > ⚠️ **Security-sensitive feature.** This mode delegates authentication entirely to your reverse proxy. Misconfiguration can expose your Gateway to unauthorized access. Read this page carefully before enabling. |
|
|
| ## When to Use |
|
|
| Use `trusted-proxy` auth mode when: |
|
|
| - You run OpenClaw behind an **identity-aware proxy** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth) |
| - Your proxy handles all authentication and passes user identity via headers |
| - You're in a Kubernetes or container environment where the proxy is the only path to the Gateway |
| - You're hitting WebSocket `1008 unauthorized` errors because browsers can't pass tokens in WS payloads |
|
|
| ## When NOT to Use |
|
|
| - If your proxy doesn't authenticate users (just a TLS terminator or load balancer) |
| - If there's any path to the Gateway that bypasses the proxy (firewall holes, internal network access) |
| - If you're unsure whether your proxy correctly strips/overwrites forwarded headers |
| - If you only need personal single-user access (consider Tailscale Serve + loopback for simpler setup) |
|
|
| ## How It Works |
|
|
| 1. Your reverse proxy authenticates users (OAuth, OIDC, SAML, etc.) |
| 2. Proxy adds a header with the authenticated user identity (e.g., `x-forwarded-user: nick@example.com`) |
| 3. OpenClaw checks that the request came from a **trusted proxy IP** (configured in `gateway.trustedProxies`) |
| 4. OpenClaw extracts the user identity from the configured header |
| 5. If everything checks out, the request is authorized |
|
|
| ## Control UI Pairing Behavior |
|
|
| When `gateway.auth.mode = "trusted-proxy"` is active and the request passes |
| trusted-proxy checks, Control UI WebSocket sessions can connect without device |
| pairing identity. |
|
|
| Implications: |
|
|
| - Pairing is no longer the primary gate for Control UI access in this mode. |
| - Your reverse proxy auth policy and `allowUsers` become the effective access control. |
| - Keep gateway ingress locked to trusted proxy IPs only (`gateway.trustedProxies` + firewall). |
|
|
| ## Configuration |
|
|
| ```json5 |
| { |
| gateway: { |
| // Use loopback for same-host proxy setups; use lan/custom for remote proxy hosts |
| bind: "loopback", |
| |
| // 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: ["nick@example.com", "admin@company.org"], |
| }, |
| }, |
| }, |
| } |
| ``` |
|
|
| If `gateway.bind` is `loopback`, include a loopback proxy address in |
| `gateway.trustedProxies` (`127.0.0.1`, `::1`, or an equivalent loopback CIDR). |
|
|
| ### Configuration Reference |
|
|
| | Field | Required | Description | |
| | ------------------------------------------- | -------- | --------------------------------------------------------------------------- | |
| | `gateway.trustedProxies` | Yes | Array of proxy IP addresses to trust. Requests from other IPs are rejected. | |
| | `gateway.auth.mode` | Yes | Must be `"trusted-proxy"` | |
| | `gateway.auth.trustedProxy.userHeader` | Yes | Header name containing the authenticated user identity | |
| | `gateway.auth.trustedProxy.requiredHeaders` | No | Additional headers that must be present for the request to be trusted | |
| | `gateway.auth.trustedProxy.allowUsers` | No | Allowlist of user identities. Empty means allow all authenticated users. | |
|
|
| ## TLS termination and HSTS |
|
|
| Use one TLS termination point and apply HSTS there. |
|
|
| ### Recommended pattern: proxy TLS termination |
|
|
| When your reverse proxy handles HTTPS for `https://control.example.com`, set |
| `Strict-Transport-Security` at the proxy for that domain. |
|
|
| - Good fit for internet-facing deployments. |
| - Keeps certificate + HTTP hardening policy in one place. |
| - OpenClaw can stay on loopback HTTP behind the proxy. |
|
|
| Example header value: |
|
|
| ```text |
| Strict-Transport-Security: max-age=31536000; includeSubDomains |
| ``` |
|
|
| ### Gateway TLS termination |
|
|
| If OpenClaw itself serves HTTPS directly (no TLS-terminating proxy), set: |
|
|
| ```json5 |
| { |
| gateway: { |
| tls: { enabled: true }, |
| http: { |
| securityHeaders: { |
| strictTransportSecurity: "max-age=31536000; includeSubDomains", |
| }, |
| }, |
| }, |
| } |
| ``` |
|
|
| `strictTransportSecurity` accepts a string header value, or `false` to disable explicitly. |
|
|
| ### Rollout guidance |
|
|
| - Start with a short max age first (for example `max-age=300`) while validating traffic. |
| - Increase to long-lived values (for example `max-age=31536000`) only after confidence is high. |
| - Add `includeSubDomains` only if every subdomain is HTTPS-ready. |
| - Use preload only if you intentionally meet preload requirements for your full domain set. |
| - Loopback-only local development does not benefit from HSTS. |
|
|
| ## Proxy Setup Examples |
|
|
| ### Pomerium |
|
|
| Pomerium passes identity in `x-pomerium-claim-email` (or other claim headers) and a JWT in `x-pomerium-jwt-assertion`. |
|
|
| ```json5 |
| { |
| 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"], |
| }, |
| }, |
| }, |
| } |
| ``` |
|
|
| Pomerium config snippet: |
|
|
| ```yaml |
| routes: |
| - from: https://openclaw.example.com |
| to: http://openclaw-gateway:18789 |
| policy: |
| - allow: |
| or: |
| - email: |
| is: nick@example.com |
| pass_identity_headers: true |
| ``` |
|
|
| ### Caddy with OAuth |
|
|
| Caddy with the `caddy-security` plugin can authenticate users and pass identity headers. |
|
|
| ```json5 |
| { |
| gateway: { |
| bind: "lan", |
| trustedProxies: ["127.0.0.1"], // Caddy's IP (if on same host) |
| auth: { |
| mode: "trusted-proxy", |
| trustedProxy: { |
| userHeader: "x-forwarded-user", |
| }, |
| }, |
| }, |
| } |
| ``` |
|
|
| Caddyfile snippet: |
|
|
| ``` |
| openclaw.example.com { |
| authenticate with oauth2_provider |
| authorize with policy1 |
| |
| reverse_proxy openclaw:18789 { |
| header_up X-Forwarded-User {http.auth.user.email} |
| } |
| } |
| ``` |
|
|
| ### nginx + oauth2-proxy |
|
|
| oauth2-proxy authenticates users and passes identity in `x-auth-request-email`. |
|
|
| ```json5 |
| { |
| gateway: { |
| bind: "lan", |
| trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP |
| auth: { |
| mode: "trusted-proxy", |
| trustedProxy: { |
| userHeader: "x-auth-request-email", |
| }, |
| }, |
| }, |
| } |
| ``` |
|
|
| nginx config snippet: |
|
|
| ```nginx |
| 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"; |
| } |
| ``` |
|
|
| ### Traefik with Forward Auth |
|
|
| ```json5 |
| { |
| gateway: { |
| bind: "lan", |
| trustedProxies: ["172.17.0.1"], // Traefik container IP |
| auth: { |
| mode: "trusted-proxy", |
| trustedProxy: { |
| userHeader: "x-forwarded-user", |
| }, |
| }, |
| }, |
| } |
| ``` |
|
|
| ## Security Checklist |
|
|
| Before enabling trusted-proxy auth, verify: |
|
|
| - [ ] **Proxy is the only path**: The Gateway port is firewalled from everything except your proxy |
| - [ ] **trustedProxies is minimal**: Only your actual proxy IPs, not entire subnets |
| - [ ] **Proxy strips headers**: Your proxy overwrites (not appends) `x-forwarded-*` headers from clients |
| - [ ] **TLS termination**: Your proxy handles TLS; users connect via HTTPS |
| - [ ] **allowUsers is set** (recommended): Restrict to known users rather than allowing anyone authenticated |
|
|
| ## Security Audit |
|
|
| `openclaw security audit` will flag trusted-proxy auth with a **critical** severity finding. This is intentional — it's a reminder that you're delegating security to your proxy setup. |
|
|
| The audit checks for: |
|
|
| - Missing `trustedProxies` configuration |
| - Missing `userHeader` configuration |
| - Empty `allowUsers` (allows any authenticated user) |
|
|
| ## Troubleshooting |
|
|
| ### "trusted_proxy_untrusted_source" |
| |
| The request didn't come from an IP in `gateway.trustedProxies`. Check: |
| |
| - Is the proxy IP correct? (Docker container IPs can change) |
| - Is there a load balancer in front of your proxy? |
| - Use `docker inspect` or `kubectl get pods -o wide` to find actual IPs |
| |
| ### "trusted_proxy_user_missing" |
|
|
| The user header was empty or missing. Check: |
|
|
| - Is your proxy configured to pass identity headers? |
| - Is the header name correct? (case-insensitive, but spelling matters) |
| - Is the user actually authenticated at the proxy? |
|
|
| ### "trusted*proxy_missing_header*\*" |
| |
| A required header wasn't present. Check: |
| |
| - Your proxy configuration for those specific headers |
| - Whether headers are being stripped somewhere in the chain |
| |
| ### "trusted_proxy_user_not_allowed" |
| |
| The user is authenticated but not in `allowUsers`. Either add them or remove the allowlist. |
| |
| ### WebSocket Still Failing |
| |
| Make sure your proxy: |
| |
| - Supports WebSocket upgrades (`Upgrade: websocket`, `Connection: upgrade`) |
| - Passes the identity headers on WebSocket upgrade requests (not just HTTP) |
| - Doesn't have a separate auth path for WebSocket connections |
| |
| ## Migration from Token Auth |
| |
| If you're moving from token auth to trusted-proxy: |
| |
| 1. Configure your proxy to authenticate users and pass headers |
| 2. Test the proxy setup independently (curl with headers) |
| 3. Update OpenClaw config with trusted-proxy auth |
| 4. Restart the Gateway |
| 5. Test WebSocket connections from the Control UI |
| 6. Run `openclaw security audit` and review findings |
| |
| ## Related |
| |
| - [Security](/gateway/security) — full security guide |
| - [Configuration](/gateway/configuration) — config reference |
| - [Remote Access](/gateway/remote) — other remote access patterns |
| - [Tailscale](/gateway/tailscale) — simpler alternative for tailnet-only access |
| |
