Authentifizierung über vertrauenswürdigen Proxy

Wann verwenden

• Sie betreiben OpenClaw hinter einem identitätsbewussten Proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + Forward-Authentifizierung).
• Ihr Proxy übernimmt die gesamte Authentifizierung und übergibt die Benutzeridentität über Header.
• Sie verwenden eine Kubernetes- oder Container-Umgebung, in der der Proxy der einzige Pfad zum Gateway ist.
• Es treten WebSocket-Fehler vom Typ 1008 unauthorized auf, weil Browser keine Token in WS-Nutzdaten übergeben können.

Wann NICHT verwenden

• Ihr Proxy authentifiziert keine Benutzer, sondern dient lediglich als TLS-Endpunkt oder Load-Balancer.
• Es gibt einen Pfad zum Gateway, der den Proxy umgeht, etwa durch Lücken in der Firewall oder internen Netzwerkzugriff.
• Sie sind nicht sicher, ob Ihr Proxy weitergeleitete Header ordnungsgemäß entfernt oder überschreibt.
• Sie benötigen lediglich persönlichen Einzelbenutzerzugriff; ziehen Sie stattdessen Tailscale Serve + loopback in Betracht.

Funktionsweise

Konfiguration

{  gateway: {    // Die Authentifizierung über einen vertrauenswürdigen Proxy erwartet standardmäßig,    // dass die Quell-IP des Proxys keine Loopback-Adresse ist    bind: "lan",     // KRITISCH: Fügen Sie hier ausschließlich die IP-Adresse(n) Ihres Proxys hinzu    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Header mit der authentifizierten Benutzeridentität (erforderlich)        userHeader: "x-forwarded-user",         // Optional: Header, die vorhanden sein MÜSSEN (Proxy-Überprüfung)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Optional: auf bestimmte Benutzer beschränken (leer = alle zulassen)        allowUsers: ["nick@example.com", "admin@company.org"],         // Optional: einen Loopback-Proxy auf demselben Host nach expliziter Zustimmung zulassen        allowLoopback: false,      },    },  },}

Konfigurationsreferenz

Kopplungsverhalten der Control UI

Wenn gateway.auth.mode = "trusted-proxy" aktiv ist und die Anfrage die Prüfungen für vertrauenswürdige Proxys besteht, können WebSocket-Sitzungen der Control UI ohne Identität eines gekoppelten Geräts eine Verbindung herstellen.

Auswirkungen auf Berechtigungsbereiche:

• WebSocket-Sitzungen der Control UI ohne Gerät stellen eine Verbindung her, erhalten jedoch standardmäßig keine Operator-Berechtigungsbereiche. OpenClaw setzt die Liste der angeforderten Berechtigungsbereiche auf [], sodass eine Sitzung, die nicht an ein genehmigtes gekoppeltes Gerät oder 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 die Kopplung abschließen kann. Siehe Unsicheres HTTP für die Control UI.
• Nur für Notfälle: gateway.controlUi.dangerouslyDisableDeviceAuth=true behält angeforderte Berechtigungsbereiche auch ohne Geräteidentität bei. Dies stellt eine erhebliche Herabstufung der Sicherheit dar; machen Sie die Änderung schnellstmöglich rückgängig. Siehe Unsicheres HTTP für die Control UI.

Begrenzung der Berechtigungsbereiche durch den Reverse-Proxy: Wenn Ihr Proxy beim WebSocket-Upgrade der Control UI x-openclaw-scopes sendet, begrenzt OpenClaw die Berechtigungsbereiche der Sitzung auf die Schnittmenge der angeforderten und der deklarierten Berechtigungsbereiche. Dieser Header gewährt keine Berechtigungsbereiche, sondern schränkt lediglich ein, welche Berechtigungsbereiche die Sitzung besitzen kann.

Auswirkungen:

• Die Kopplung ist in diesem Modus nicht länger die primäre Zugangsschranke für die Control UI.
• Die Authentifizierungsrichtlinie Ihres Reverse-Proxys und allowUsers bilden die effektive Zugriffskontrolle.
• Beschränken Sie den eingehenden Gateway-Datenverkehr ausschließlich auf vertrauenswürdige Proxy-IP-Adressen (gateway.trustedProxies + Firewall).

Benutzerdefinierte WebSocket-Clients sind keine Sitzungen der Control UI. gateway.controlUi.dangerouslyDisableDeviceAuth gewährt beliebigen Clients mit client.mode: "backend" oder CLI-ähnlichen Clients keine Berechtigungsbereiche. Benutzerdefinierte Automatisierungen sollten die Geräteidentität und Kopplung, den reservierten direkten lokalen Hilfspfad für Backends mit client.id: "gateway-client" oder das Plugin für administrative HTTP-RPC verwenden, wenn eine HTTP-Anfrage-Antwort-Schnittstelle besser geeignet ist.

Header für Operator-Berechtigungsbereiche

Die Authentifizierung über einen vertrauenswürdigen Proxy ist ein identitätstragender HTTP-Modus. Aufrufer können daher bei HTTP-API-Anfragen optional Operator-Berechtigungsbereiche mit x-openclaw-scopes deklarieren.

Hinweis: WebSocket-Berechtigungsbereiche werden durch den Gateway-Protokoll-Handshake und die Bindung der Geräteidentität bestimmt. Bei WebSocket-Upgrade-Anfragen der Control UI begrenzt x-openclaw-scopes lediglich die ausgehandelten Berechtigungsbereiche der Sitzung und gewährt keine. Siehe 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 Menge an Berechtigungsbereichen.
• Wenn der Header vorhanden, aber leer ist, deklariert die Anfrage keine Operator-Berechtigungsbereiche.
• Wenn der Header fehlt, greifen normale identitätstragende HTTP-APIs auf die standardmäßige Menge an Operator-Berechtigungsbereichen zurück (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Durch Gateway-Authentifizierung geschützte HTTP-Routen von Plugins sind standardmäßig stärker eingeschränkt: Wenn x-openclaw-scopes fehlt, fällt ihr Laufzeit-Berechtigungsbereich ausschließlich auf operator.write zurück.
• HTTP-Anfragen mit Browser-Ursprung müssen auch nach erfolgreicher Authentifizierung über einen vertrauenswürdigen Proxy weiterhin gateway.controlUi.allowedOrigins oder den bewusst aktivierten Rückgriff auf den Host-Header bestehen.

Praxisregel: Senden Sie x-openclaw-scopes explizit, wenn eine Anfrage über einen vertrauenswürdigen Proxy stärker als die Standardwerte eingeschränkt sein soll oder wenn eine durch Gateway-Authentifizierung geschützte Plugin-Route einen umfassenderen Berechtigungsbereich als den Schreibzugriff benötigt.

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

Empfehlungen für die Einführung

• Beginnen Sie während der Überprüfung des Datenverkehrs zunächst mit einer kurzen maximalen Gültigkeitsdauer, beispielsweise max-age=300.
• Erhöhen Sie den Wert erst bei ausreichender Sicherheit auf eine lange Gültigkeitsdauer, beispielsweise max-age=31536000.
• Fügen Sie includeSubDomains nur hinzu, wenn jede Subdomain für HTTPS bereit ist.
• Verwenden Sie die Preload-Funktion nur, wenn Sie die Preload-Anforderungen für Ihre gesamte Domain-Gruppe bewusst erfüllen.
• Eine ausschließlich über loopback erreichbare lokale Entwicklungsumgebung profitiert nicht von HSTS.

Beispiele für die Proxy-Einrichtung

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // IP-Adresse von Pomerium    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

Der Gateway-Start lehnt die Trusted-Proxy-Authentifizierung ab, wenn zusätzlich ein gemeinsames Token konfiguriert ist (gateway.auth.token oder OPENCLAW_GATEWAY_TOKEN). Beide schließen sich gegenseitig aus, da ein gemeinsames Token Aufrufern auf demselben Host die Authentifizierung über einen völlig anderen Pfad als die von diesem Modus erzwungene, durch den Proxy verifizierte Identität ermöglichen würde.

Wenn der Start mit einem Fehler wie gateway auth mode is trusted-proxy, but a shared token is also configured fehlschlägt:

• Entfernen Sie das gemeinsame Token, wenn Sie den Trusted-Proxy-Modus verwenden, oder
• ändern Sie gateway.auth.mode in "token", wenn Sie eine tokenbasierte Authentifizierung verwenden möchten.

Trusted-Proxy-Identitätsheader über local loopback werden weiterhin nach dem Fail-Closed-Prinzip abgelehnt: 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. Ein Token-Fallback wird im Trusted-Proxy-Modus bewusst weiterhin nicht unterstützt.

Sicherheitscheckliste

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

• [ ] Der Proxy ist der einzige Zugriffsweg: Der Gateway-Port ist durch eine Firewall für alle Zugriffe außer denen Ihres Proxys gesperrt.
• [ ] trustedProxies ist minimal: Nur die tatsächlichen IP-Adressen Ihres Proxys, nicht vollständige Subnetze.
• [ ] Die Loopback-Proxyquelle ist beabsichtigt: Die Trusted-Proxy-Authentifizierung lehnt Anfragen aus Loopback-Quellen nach dem Fail-Closed-Prinzip ab, sofern gateway.auth.trustedProxy.allowLoopback nicht ausdrücklich für einen Proxy auf demselben Host aktiviert ist.
• [ ] Der Proxy entfernt Header: Ihr Proxy überschreibt von Clients stammende x-forwarded-*-Header, statt Werte anzuhängen.
• [ ] TLS-Terminierung: Ihr Proxy verarbeitet TLS; Benutzer stellen die Verbindung über HTTPS her.
• [ ] allowedOrigins ist explizit festgelegt: Eine Control UI außerhalb von local loopback verwendet explizite gateway.controlUi.allowedOrigins.
• [ ] allowUsers ist festgelegt (empfohlen): Beschränken Sie den Zugriff auf bekannte Benutzer, statt jeden authentifizierten Benutzer zuzulassen.
• [ ] Keine gemischte Token-Konfiguration: Legen Sie nicht gleichzeitig gateway.auth.token und gateway.auth.mode: "trusted-proxy" fest.
• [ ] Der lokale Passwort-Fallback ist geschützt: Wenn Sie gateway.auth.password für interne direkte Aufrufer konfigurieren, schützen Sie den Gateway-Port mit einer Firewall, damit Remote-Clients außerhalb des Proxys nicht direkt darauf zugreifen können.

Sicherheitsprüfung

openclaw security audit kennzeichnet die Trusted-Proxy-Authentifizierung mit einem Befund des Schweregrads kritisch. Dies ist beabsichtigt; es erinnert Sie daran, dass Sie die Sicherheit an Ihre Proxy-Konfiguration delegieren.

Die Prüfung kontrolliert Folgendes:

• Grundlegende Warnung bzw. kritischer Hinweis gateway.trusted_proxy_auth.
• Fehlende trustedProxies-Konfiguration.
• Fehlende userHeader-Konfiguration.
• Leere allowUsers-Liste (lässt jeden authentifizierten Benutzer zu).
• Aktiviertes allowLoopback für Proxyquellen auf demselben Host.

Separate, nicht speziell auf Trusted Proxy bezogene Befunde gelten ebenfalls, wenn die Control UI erreichbar ist: Platzhalter oder fehlende gateway.controlUi.allowedOrigins sowie der Origin-Fallback über den Host-Header.

Fehlerbehebung

Migration von der Token-Authentifizierung

Verwandte Themen

• Konfiguration — Konfigurationsreferenz
• Operator-Scopes — Rollen, Scopes und Genehmigungsprüfungen
• Remote-Zugriff — weitere Muster für den Remote-Zugriff
• Sicherheit — vollständiger Sicherheitsleitfaden
• Tailscale — einfachere Alternative für den ausschließlichen Zugriff über ein Tailnet