Authentifizierung über vertrauenswürdigen Proxy

Wann verwenden

Verwenden Sie den Authentifizierungsmodus trusted-proxy, wenn:

• Sie OpenClaw hinter einem identitätsbewussten Proxy betreiben (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Ihr Proxy die gesamte Authentifizierung übernimmt und die Benutzeridentität über Header weitergibt.
• Sie sich in einer Kubernetes- oder Containerumgebung befinden, in der der Proxy der einzige Pfad zum Gateway ist.
• Sie WebSocket-Fehler vom Typ 1008 unauthorized erhalten, weil Browser keine Tokens in WS-Payloads übergeben können.

Wann NICHT verwenden

• Wenn Ihr Proxy Benutzer nicht authentifiziert (nur TLS-Terminierung oder Load Balancer).
• Wenn es irgendeinen Pfad zum Gateway gibt, der den Proxy umgeht (Firewall-Lücken, interner Netzwerkzugriff).
• Wenn Sie unsicher sind, ob Ihr Proxy weitergeleitete Header korrekt entfernt/überschreibt.
• Wenn Sie nur persönlichen Einzelbenutzerzugriff benötigen (erwägen Sie Tailscale Serve + Loopback für eine einfachere Einrichtung).

Funktionsweise

Pairing-Verhalten der Control UI

Wenn gateway.auth.mode = "trusted-proxy" aktiv ist und die Anfrage die Trusted-Proxy-Prüfungen besteht, können Control-UI-WebSocket-Sitzungen ohne Geräte-Pairing-Identität verbunden werden.

Auswirkungen auf den Scope:

• Gerätelose Control-UI-WebSocket-Sitzungen verbinden sich, erhalten aber standardmäßig keine Operator-Scopes. OpenClaw leert die angeforderte Scope-Liste auf [], sodass eine Sitzung, die nicht an ein genehmigtes gekoppeltes Gerät/Token gebunden ist, keine Berechtigungen selbst deklarieren kann.
• Wenn Methoden nach einer erfolgreichen WebSocket-Verbindung mit missing scope fehlschlagen, verwenden Sie HTTPS, damit der Browser eine Geräteidentität erzeugen und das Pairing abschließen kann. Siehe unsicheres HTTP für die Control UI.
• Nur für den Notfall: gateway.controlUi.dangerouslyDisableDeviceAuth=true behält angeforderte Scopes auch ohne Geräteidentität bei. Dies ist eine schwerwiegende Sicherheitsherabstufung; machen Sie sie schnell rückgängig. Siehe unsicheres HTTP für die Control UI.

Scope-Begrenzung durch Reverse Proxy:

• Wenn Ihr Proxy x-openclaw-scopes bei der Control-UI-WebSocket-Upgrade-Anfrage sendet, begrenzt OpenClaw die Sitzungs-Scopes auf die Schnittmenge aus den angeforderten Scopes und den deklarierten Scopes. Dieser Header gewährt keine Scopes; er schränkt nur ein, was die Sitzung halten kann.

Auswirkungen:

• Pairing ist in diesem Modus nicht mehr die primäre Hürde für den Zugriff auf die Control UI.
• Die Authentifizierungsrichtlinie Ihres Reverse Proxys und allowUsers werden zur effektiven Zugriffskontrolle.
• Beschränken Sie den Gateway-Ingress ausschließlich auf vertrauenswürdige Proxy-IPs (gateway.trustedProxies + Firewall).

Benutzerdefinierte WebSocket-Clients sind keine Control-UI-Sitzungen. gateway.controlUi.dangerouslyDisableDeviceAuth gewährt beliebigen Clients mit client.mode: "backend" oder CLI-artigen Clients keine Scopes. Benutzerdefinierte Automatisierung sollte Geräteidentität/Pairing, den reservierten direkten lokalen Backend-Hilfspfad client.id: "gateway-client" oder das Admin-HTTP-RPC-Plugin verwenden, wenn eine HTTP-Anfrage/Antwort-Oberfläche besser passt.

Konfiguration

{  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: ["nick@example.com", "admin@company.org"],         // Optional: allow a same-host loopback proxy after explicit opt-in        allowLoopback: false,      },    },  },}

Konfigurationsreferenz

TLS-Terminierung und HSTS

Verwenden Sie einen einzigen TLS-Terminierungspunkt und wenden Sie HSTS dort an.

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

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

Rollout-Empfehlungen

• Beginnen Sie zuerst mit einer kurzen maximalen Gültigkeitsdauer (zum Beispiel max-age=300), während Sie den Traffic validieren.
• Erhöhen Sie erst auf langlebige Werte (zum Beispiel max-age=31536000), wenn die Sicherheit hoch ist.
• Fügen Sie includeSubDomains nur hinzu, wenn jede Subdomain HTTPS-bereit ist.
• Verwenden Sie Preload nur, wenn Sie die Preload-Anforderungen für Ihren vollständigen Domain-Satz absichtlich erfüllen.
• Reine Loopback-Entwicklung lokal profitiert nicht von HSTS.

Beispiele für Proxy-Einrichtung

{  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: 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",      },    },  },}

Gemischte Token-Konfiguration

OpenClaw lehnt mehrdeutige Konfigurationen ab, bei denen sowohl ein gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN) als auch der Modus trusted-proxy gleichzeitig aktiv sind. Gemischte Token-Konfigurationen können dazu führen, dass Loopback-Anfragen stillschweigend über den falschen Authentifizierungspfad authentifiziert werden.

Wenn beim Start ein Fehler mixed_trusted_proxy_token angezeigt wird:

• Entfernen Sie das gemeinsame Token, wenn Sie den Trusted-Proxy-Modus verwenden, oder
• Wechseln Sie gateway.auth.mode zu "token", wenn Sie tokenbasierte Authentifizierung beabsichtigen.

Loopback-Trusted-Proxy-Identitäts-Header verweigern weiterhin sicher: Aufrufer auf demselben Host werden nicht stillschweigend als Proxy-Benutzer authentifiziert. Interne OpenClaw-Aufrufer, die den Proxy umgehen, können sich stattdessen mit gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD authentifizieren. Token-Fallback bleibt im Trusted-Proxy-Modus absichtlich nicht unterstützt.

Header für Operator-Scopes

Trusted-Proxy-Authentifizierung ist ein HTTP-Modus, der Identität trägt, daher können Aufrufer optional Operator-Scopes mit x-openclaw-scopes für HTTP-API-Anfragen deklarieren.

Hinweis: WebSocket-Scopes werden durch den Gateway-Protokoll-Handshake und die Geräteidentitätsbindung bestimmt. Bei WebSocket-Upgrade-Anfragen der Control UI ist x-openclaw-scopes nur eine Obergrenze für die ausgehandelten Sitzungs-Scopes, keine Gewährung. Informationen zum WebSocket-Scope-Verhalten mit Trusted Proxy finden Sie unter Kopplungsverhalten der Control UI.

Beispiele:

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

Verhalten:

• Wenn der Header vorhanden ist, berücksichtigt OpenClaw die deklarierte Scope-Menge.
• Wenn der Header vorhanden, aber leer ist, deklariert die Anfrage keine Operator-Scopes.
• Wenn der Header fehlt, fallen normale identitätstragende HTTP-APIs auf die standardmäßige Operator-Default-Scope-Menge zurück.
• Gateway-Auth-Plugin-HTTP-Routen sind standardmäßig enger gefasst: Wenn x-openclaw-scopes fehlt, fällt ihr Laufzeit-Scope auf operator.write zurück.
• HTTP-Anfragen aus Browser-Ursprüngen müssen weiterhin gateway.controlUi.allowedOrigins bestehen (oder den bewusst gewählten Host-Header-Fallback-Modus), auch nachdem die Trusted-Proxy-Authentifizierung erfolgreich war.
• Für WebSocket-Sitzungen der Control UI ist x-openclaw-scopes eine Scope-Obergrenze, wenn der Header in der Upgrade-Anfrage vorhanden ist. Ein leerer Wert ergibt keine Scopes.

Praktische Regel: Senden Sie x-openclaw-scopes explizit, wenn eine Trusted-Proxy-Anfrage enger als die Defaults sein soll oder wenn eine Gateway-Auth-Plugin-Route etwas Stärkeres als Schreib-Scope benötigt.

Sicherheits-Checkliste

Prüfen Sie vor dem Aktivieren der Trusted-Proxy-Authentifizierung:

• [ ] Proxy ist der einzige Pfad: Der Gateway-Port ist per Firewall vor allem außer Ihrem Proxy geschützt.
• [ ] trustedProxies ist minimal: Nur Ihre tatsächlichen Proxy-IPs, keine ganzen Subnetze.
• [ ] Loopback-Proxy-Quelle ist beabsichtigt: Trusted-Proxy-Authentifizierung verweigert Loopback-Quellanfragen sicher, sofern gateway.auth.trustedProxy.allowLoopback nicht explizit für einen Proxy auf demselben Host aktiviert ist.
• [ ] Proxy entfernt Header: Ihr Proxy überschreibt x-forwarded-*-Header von Clients, statt sie anzuhängen.
• [ ] TLS-Terminierung: Ihr Proxy übernimmt TLS; Benutzer verbinden sich per HTTPS.
• [ ] allowedOrigins ist explizit: Nicht-Loopback-Control-UI verwendet explizite gateway.controlUi.allowedOrigins.
• [ ] allowUsers ist gesetzt (empfohlen): Beschränken Sie den Zugriff auf bekannte Benutzer, statt beliebige authentifizierte Benutzer zuzulassen.
• [ ] Keine gemischte Token-Konfiguration: Setzen Sie nicht gleichzeitig gateway.auth.token und gateway.auth.mode: "trusted-proxy".
• [ ] Lokaler Passwort-Fallback ist privat: Wenn Sie gateway.auth.password für interne direkte Aufrufer konfigurieren, schützen Sie den Gateway-Port per Firewall, damit entfernte Nicht-Proxy-Clients ihn nicht direkt erreichen können.

Sicherheitsaudit

openclaw security audit markiert Trusted-Proxy-Authentifizierung mit einem Befund der Schwere kritisch. Das ist beabsichtigt — es erinnert daran, dass Sie die Sicherheit an Ihre Proxy-Einrichtung delegieren.

Das Audit prüft auf:

• Basiswarnung/kritische Erinnerung gateway.trusted_proxy_auth
• Fehlende trustedProxies-Konfiguration
• Fehlende userHeader-Konfiguration
• Leere allowUsers (erlaubt jeden authentifizierten Benutzer)
• Aktiviertes allowLoopback für Proxy-Quellen auf demselben Host
• Wildcard- oder fehlende Browser-Origin-Richtlinie auf exponierten Control-UI-Oberflächen

Fehlerbehebung

Migration von Token-Authentifizierung

Wenn Sie von Token-Authentifizierung zu Trusted Proxy wechseln:

Verwandte Themen

• Konfiguration — Konfigurationsreferenz
• Remotezugriff — andere Remotezugriffsmuster
• Sicherheit — vollständiger Sicherheitsleitfaden
• Tailscale — einfachere Alternative für reinen Tailnet-Zugriff