Authentifizierung über vertrauenswürdigen Proxy

Verwendung

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

Nicht verwenden

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

Funktionsweise

Konfiguration

{  gateway: {    // Bei Trusted-Proxy-Authentifizierung darf die Quell-IP des Proxys standardmäßig keine Loopback-Adresse sein    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: nach ausdrücklicher Aktivierung einen Loopback-Proxy auf demselben Host zulassen        allowLoopback: false,         // Optional: authentifizierten Proxy-Benutzern die Registrierung neuer Browsergeräte erlauben        deviceAutoApprove: {          enabled: false,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

Konfigurationsreferenz

Automatische Gerätegenehmigung

Die Trusted-Proxy-Authentifizierung kann optional die Proxy-Identität als Genehmigungsgrenze für neue Browsergeräte verwenden:

{  gateway: {    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",        allowUsers: ["operator@example.com"],        deviceAutoApprove: {          enabled: true,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

Der Standardwert ist enabled: false. Wenn die Option aktiviert ist, gelten alle folgenden Regeln:

1. Der WebSocket muss über die Methode trusted-proxy mit einer nicht leeren Benutzeridentität authentifiziert worden sein, die allowUsers erfüllt, wenn eine Zulassungsliste konfiguriert ist. Verbindungen über Token, Passwort, Tailscale oder ohne Authentifizierung verwenden diese Richtlinie niemals.
2. Nur ein neues Browsergerät der Control UI oder von WebChat kann automatisch genehmigt werden. Jede Anfrage für ein vorhandenes Gerät, einschließlich einer Erweiterung der Berechtigungsbereiche, bleibt zur manuellen Genehmigung mit openclaw devices approve <requestId> ausstehend.
3. Das Gerät wird mit der Rolle operator genehmigt. Wenn die Verbindungsanfrage Berechtigungsbereiche enthält, entspricht die Gewährung exakt der Schnittmenge aus den angeforderten Berechtigungsbereichen und deviceAutoApprove.scopes. Lässt die Anfrage die Berechtigungsbereiche aus, wird die konfigurierte Liste gewährt. Wenn diese Liste nicht angegeben ist, werden standardmäßig operator.read, operator.write und operator.approvals verwendet. Die resultierende Gewährung wird anschließend zusätzlich durch den Proxy-Header x-openclaw-scopes der Verbindung begrenzt, sofern dieser vorhanden ist. Dadurch begrenzt ein Proxy, der die Berechtigungsbereiche eines Benutzers einschränkt, auch die dauerhafte Gerätegewährung und nicht nur die Sitzung; ein vorhandener, aber leerer Header gewährt keine Berechtigungsbereiche. Diese Begrenzung gilt auch, wenn der Client seine eigene Liste der Berechtigungsbereiche auslässt.
4. operator.admin ist nur zulässig, wenn es ausdrücklich in deviceAutoApprove.scopes aufgeführt wird. Ist es aufgeführt, kann jeder über den Proxy authentifizierte Benutzer vollständige Administratorrechte für ein neues Browsergerät anfordern und automatisch erhalten. Anfragen ohne Berechtigungsbereiche erhalten automatisch vollständige Administratorrechte. openclaw security audit meldet den KRITISCHEN Befund gateway.trusted_proxy_device_auto_approve_admin, und der Gateway protokolliert beim Start einmalig eine Warnung. Bevorzugen Sie die manuelle Administratorgenehmigung mit openclaw devices approve oder openclaw devices rotate, bis identitätsspezifische Rollen verfügbar sind.

Kopplungsverhalten 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 Kopplungsidentität des Geräts eine Verbindung herstellen.

Auswirkungen auf Berechtigungsbereiche:

• Control-UI-WebSocket-Sitzungen ohne Gerät stellen eine Verbindung her, erhalten standardmäßig jedoch keine Operator-Berechtigungsbereiche. OpenClaw leert die Liste der angeforderten Berechtigungsbereiche zu [], 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 der Control UI.
• Ältere Konfigurationen, die noch den außer Betrieb genommenen Schlüssel gateway.controlUi.dangerouslyDisableDeviceAuth=true enthalten, verwenden die begrenzte Upgrade-Migration der 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 aus den angeforderten und den deklarierten Berechtigungsbereichen. Dieser Header gewährt keine Berechtigungsbereiche, sondern schränkt lediglich ein, welche Berechtigungsbereiche die Sitzung besitzen kann. Wenn deviceAutoApprove.enabled wahr ist, gilt dieselbe Begrenzung auch für die dauerhafte Gerätegewährung, die durch die automatische Gerätegenehmigung geschrieben wird. Ein automatisch genehmigtes Gerät besitzt somit niemals mehr Berechtigungsbereiche, als der Proxy deklariert hat.

Auswirkungen:

• Die Kopplung ist nicht mehr die primäre Zugriffssperre für den gerätelosen Zugriff auf die Control UI. Wenn deviceAutoApprove.enabled wahr ist, wird die Proxy-Identität außerdem zur Genehmigungssperre für die Registrierung neuer Browsergeräte.
• Die Authentifizierungsrichtlinie Ihres Reverse-Proxys und allowUsers bilden die effektive Zugriffskontrolle.
• Beschränken Sie den Gateway-Eingang ausschließlich auf vertrauenswürdige Proxy-IP-Adressen (gateway.trustedProxies + Firewall).

Benutzerdefinierte WebSocket-Clients sind keine Control-UI-Sitzungen. Die außer Betrieb genommene Upgrade-Eingabe der Control UI gewährt beliebigen client.mode: "backend"- oder CLI-artigen Clients keinen temporären Zugriff. Benutzerdefinierte Automatisierungen sollten die Geräteidentität/Kopplung, den reservierten direkten lokalen Backend-Hilfspfad client.id: "gateway-client" oder das Admin-HTTP-RPC-Plugin verwenden, wenn eine HTTP-Anfrage-/Antwortschnittstelle besser geeignet ist.

Header für Operator-Berechtigungsbereiche

Die Trusted-Proxy-Authentifizierung ist ein identitätstragender HTTP-Modus, daher können Aufrufer bei HTTP-API-Anfragen optional Operator-Berechtigungsumfänge mit x-openclaw-scopes deklarieren.

Hinweis: WebSocket-Berechtigungsumfänge werden durch den Gateway-Protokoll-Handshake und die Bindung der Geräteidentität bestimmt. Bei WebSocket-Upgrade-Anfragen der Control UI ist x-openclaw-scopes lediglich eine Obergrenze für die ausgehandelten Sitzungsberechtigungsumfänge, keine Gewährung. 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 Berechtigungsumfängen.
• Wenn der Header vorhanden, aber leer ist, deklariert die Anfrage keine Operator-Berechtigungsumfänge.
• Wenn der Header fehlt, greifen normale identitätstragende HTTP-APIs auf die standardmäßige Menge an Operator-Berechtigungsumfängen zurück (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Durch Gateway-Authentifizierung geschützte Plugin-HTTP-Routen sind standardmäßig restriktiver: Wenn x-openclaw-scopes fehlt, greift ihr Laufzeit-Berechtigungsumfang ausschließlich auf operator.write zurück.
• HTTP-Anfragen mit Browser-Ursprung müssen auch nach erfolgreicher Trusted-Proxy-Authentifizierung weiterhin gateway.controlUi.allowedOrigins (oder den bewusst aktivierten Host-Header-Fallbackmodus) passieren.

Praxisregel: Senden Sie x-openclaw-scopes ausdrücklich, wenn eine Trusted-Proxy-Anfrage restriktiver als die Standardwerte sein soll oder wenn eine durch Gateway-Authentifizierung geschützte Plugin-Route einen stärkeren als den Schreibberechtigungsumfang 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",      },    },  },}

Hinweise zur Einführung

• Beginnen Sie zunächst mit einer kurzen maximalen Gültigkeitsdauer (zum Beispiel max-age=300), während Sie den Datenverkehr validieren.
• Erhöhen Sie sie erst dann auf langfristige Werte (zum Beispiel max-age=31536000), wenn eine hohe Sicherheit besteht.
• Fügen Sie includeSubDomains nur hinzu, wenn jede Subdomain für HTTPS bereit ist.
• Verwenden Sie Preloading nur, wenn Sie die Preload-Anforderungen für Ihre gesamte Domainmenge 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"], // IP-Adresse des Caddy-/Sidecar-Proxys    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"], // IP-Adresse von nginx/oauth2-proxy    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"], // IP-Adresse des Traefik-Containers    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 gemeinsam verwendetes Token konfiguriert ist (gateway.auth.token oder OPENCLAW_GATEWAY_TOKEN). Beide schließen sich gegenseitig aus, weil ein gemeinsam verwendetes Token es Aufrufern auf demselben Host ermöglichen würde, sich über einen völlig anderen Pfad als die von diesem Modus durchgesetzte, vom Proxy verifizierte Identität zu authentifizieren.

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 gemeinsam verwendete 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äts-Header über Loopback schlagen weiterhin sicher fehl: 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 weiterhin bewusst nicht unterstützt.

Sicherheitscheckliste

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

• [ ] Der Proxy ist der einzige Pfad: Der Gateway-Port ist durch eine Firewall für alles außer Ihrem Proxy gesperrt.
• [ ] trustedProxies ist minimal: Nur die tatsächlichen IP-Adressen Ihres Proxys, keine ganzen Subnetze.
• [ ] Eine Loopback-Proxyquelle ist beabsichtigt: Die Trusted-Proxy-Authentifizierung schlägt bei Anfragen aus einer Loopback-Quelle sicher fehl, 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 sie anzuhängen.
• [ ] TLS-Terminierung: Ihr Proxy verarbeitet TLS; Benutzer stellen die Verbindung über HTTPS her.
• [ ] allowedOrigins ist ausdrücklich festgelegt: Eine nicht über Loopback erreichbare Control UI verwendet ausdrücklich 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 sowohl gateway.auth.token als auch gateway.auth.mode: "trusted-proxy" fest.
• [ ] Der lokale Passwort-Fallback ist privat: Wenn Sie gateway.auth.password für interne direkte Aufrufer konfigurieren, schützen Sie den Gateway-Port durch eine Firewall, damit entfernte Clients außerhalb des Proxys nicht direkt darauf zugreifen können.
• [ ] Die automatische Gerätegenehmigung ist beabsichtigt: Wenn deviceAutoApprove.enabled wahr ist, behandeln Sie die Sicherheit des Reverse-Proxy-Kontos als Grenze für die Geräteregistrierung und halten Sie die Liste der gewährten Berechtigungsumfänge auf Nicht-Administratorrechte beschränkt und minimal.

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-Einrichtung delegieren.

Die Prüfung kontrolliert Folgendes:

• Grundlegende gateway.trusted_proxy_auth-Warnung bzw. kritische Erinnerung.
• Fehlende trustedProxies-Konfiguration.
• Fehlende userHeader-Konfiguration.
• Leeres allowUsers (lässt jeden authentifizierten Benutzer zu).
• Aktiviertes allowLoopback für Proxyquellen auf demselben Host.
• Aktivierte automatische Genehmigung von Browsergeräten (delegiert die Kopplung neuer Geräte an die Proxy-Identität).

Separate, nicht speziell auf Trusted-Proxy bezogene Befunde gelten ebenfalls immer dann, wenn die Control UI verfügbar gemacht wird: Platzhalterwert oder fehlendes gateway.controlUi.allowedOrigins sowie der Host-Header-Ursprungs-Fallback.

Fehlerbehebung

Migration von Token-Authentifizierung

Verwandte Themen

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