Trusted-Proxy-Authentifizierung in OpenClaw

Trusted-Proxy-Authentifizierung ist der Modus für Gateways hinter einem identitätsbewussten Proxy: Der Proxy authentifiziert die Person, fügt einen Header mit ihrer Identität hinzu, und das Gateway vertraut diesem Header, aber nur, wenn er vom Proxy kommt. Die Dokumentation beginnt mit der Warnung, dass eine Fehlkonfiguration das Gateway offenlegt, und der größte Teil der Seite ist die Liste der Prüfungen, die dieses Vertrauen sicher machen. Hier ist sie, in der Reihenfolge, in der das Gateway sie auswertet.

Wann und wie

• Setzen Sie ihn hinter Pomerium, Caddy mit OAuth, nginx mit oauth2-proxy oder Traefik Forward Auth ein, in Container-Umgebungen, in denen der Proxy der einzige Weg ist, oder wenn Browser auf WebSocket-Fehler wegen fehlender Autorisierung stoßen, weil sie im Handshake keine Tokens übergeben können; verwenden Sie ihn nicht, wenn der Proxy nur TLS terminiert, wenn irgendein Pfad den Proxy umgeht, wenn Sie nicht sicher sind, ob der Proxy weitergeleitete Header entfernt, oder für den persönlichen Einzelnutzerzugriff, bei dem ein Tailnet plus Loopback einfacher ist.
• Der Ablauf: Der Proxy authentifiziert den Benutzer, fügt einen Identitäts-Header wie den Forwarded-User-Header hinzu, das Gateway prüft, ob die Anfrage von einer vertrauenswürdigen Proxy-Adresse kam, liest die erforderlichen Header und die Benutzeridentität und autorisiert, wenn die Benutzer-Zulassungsliste, sofern gesetzt, den Benutzer enthält; die Konfiguration bindet an das lokale Netzwerk, führt nur die Proxy-Adressen oder -Bereiche auf und setzt den Auth-Modus, den Benutzer-Header, optionale erforderliche Header, eine optionale Benutzer-Zulassungsliste, wobei Loopback und die automatische Gerätefreigabe standardmäßig ausgeschaltet sind.
• Laufzeitregeln der Reihe nach: Proxy-typischer Traffic wird vor der Gateway-Authentifizierung zugeordnet und muss von einem vertrauenswürdigen Proxy kommen, dessen Client-Adress-Header zu einem Nicht-Loopback-Client auflösen, sonst weisen Gateway-authentifizierte Routen ihn wegen fehlender Proxy-Zuordnung ab; der Proxy muss die Forwarded-for-Kette sicher überschreiben, wobei der Real-Address-Header nur akzeptiert wird, wenn sein Fallback aktiviert ist; Loopback-Quellen werden abgewiesen, es sei denn, das Opt-in steht auf true und Loopback ist zusätzlich als vertrauenswürdiger Proxy eingetragen; Quellen, die einer der eigenen Interface-Adressen des Hosts entsprechen, werden als Schutz gegen Spoofing abgewiesen, und eine fehlgeschlagene Interface-Erkennung führt ebenfalls zur Abweisung; danach müssen die erforderlichen Header und der Benutzer-Header vorhanden und nicht leer sein, und die Benutzer-Zulassungsliste muss den Benutzer enthalten.
• Hinweise auf weitergeleitete Header bei einer Loopback-Anfrage schließen diese vom lokalen Direkt-Passwort-Fallback und von der Prüfung per Geräteidentität aus, während die Trusted-Proxy-Authentifizierung trotzdem fehlschlägt; interne Clients, die nicht über den Proxy laufen, verwenden das Gateway-Passwort, das der Status-Befehl ohne URL-Override automatisch auswählt; die Liste vertrauenswürdiger Proxys akzeptiert Adressbereiche in einfacher oder in gemappter Form, und ein gemapptes Präfix, das alles abdeckt, braucht für Loopback trotzdem das Loopback-Opt-in.

Ein Gateway-Token kann die Proxy-Authentifizierung nicht ersetzen.

Berechtigungen, automatische Freigabe und der Scopes-Header

Identitäts-Scopes geben ausgewählten verifizierten Benutzern Scopes nur für die Sitzung, ohne ihre Geräteberechtigung zu erweitern: Der Schlüssel ist die Proxy-Identität oder der Tailnet-Login, E-Mail-Adressen werden ohne Beachtung der Groß- und Kleinschreibung abgeglichen, die Berechtigung wird mit den für das Gerät autorisierten Scopes vereinigt und dann durch einen expliziten Scopes-Header begrenzt, und Verbindungen per Token, per Passwort oder ohne Authentifizierung erhalten nie eine. Die automatische Gerätefreigabe, standardmäßig aus, nutzt die Proxy-Identität als Freigabegrenze für neue Browser- und native Operator-Geräte sowie für Scope-Upgrades mit demselben Schlüssel: Nur Trusted-Proxy-Verbindungen mit einer nicht leeren Identität, die die Zulassungsliste passiert hat, kommen in Frage, Verbindungen mit der Node-Rolle und Rollen-Upgrades nie, angeforderte Scopes werden mit der konfigurierten Liste geschnitten (read, write, approvals und questions, wenn nichts gesetzt ist, nie erweitert), der Scopes-Header des Proxys begrenzt auch die dauerhafte Berechtigung, und wer admin in die Liste einträgt, ermöglicht jedem Proxy-Benutzer, ein Gerät mit vollen Admin-Rechten zu erhalten, was das Sicherheitsaudit als kritisch meldet und wovor das Gateway beim Start warnt. Sitzungen der Steueroberfläche ohne Gerät können ihre Scopes nicht selbst deklarieren: Ihre Liste wird geleert und eine passende Identitätsberechtigung angewendet; ein Fehler wegen eines fehlenden Scopes nach erfolgreichem Verbindungsaufbau bedeutet, dass Sie neu laden müssen, damit der Browser seine Geräteidentität koppelt. Der Scopes-Header deklariert Scopes, wenn er vorhanden ist, deklariert keine, wenn er vorhanden, aber leer ist, und fällt auf den Standardsatz für Operatoren zurück, wenn er fehlt, während Gateway-authentifizierte Plugin-Routen nur auf write zurückfallen.

TLS, gemischte Tokens und das Audit

• Terminieren Sie TLS an genau einer Stelle und setzen Sie dort den Strict-Transport-Header: am Proxy bei aus dem Internet erreichbaren Deployments, mit dem Gateway auf Loopback dahinter, oder am Gateway mit aktiviertem TLS und dem Strict-Transport-Security-Header, wenn es selbst HTTPS ausliefert; beginnen Sie mit einem kurzen Max-Age, erhöhen Sie ihn erst, wenn Sie sich sicher sind, fügen Sie das Subdomain-Flag nur hinzu, wenn jede Subdomain bereit ist, und lassen Sie den Header bei reiner Loopback-Entwicklung weg.
• Der Start lehnt die Trusted-Proxy-Authentifizierung ab, wenn zusätzlich ein gemeinsames Token konfiguriert ist, weil ein Token Aufrufern auf demselben Host erlauben würde, sich über einen anderen Weg als die vom Proxy verifizierte Identität zu authentifizieren; entfernen Sie das Token oder wechseln Sie den Modus, und denken Sie daran, dass Loopback-Identitäts-Header weiterhin sicher abgewiesen werden (fail closed) und dass ein Token-Fallback absichtlich nicht unterstützt wird.
• Das Sicherheitsaudit stuft den Modus bewusst als kritisch ein und prüft auf eine fehlende Liste vertrauenswürdiger Proxys, einen fehlenden Benutzer-Header, eine leere Benutzer-Zulassungsliste, ein aktiviertes Loopback-Opt-in und eine aktivierte automatische Gerätefreigabe; die Checkliste ergänzt, dass der Proxy der einzige Weg ist, die Liste vertrauenswürdiger Proxys minimal ist, der Proxy weitergeleitete Header überschreibt und die Forwarded-for-Kette neu aufbaut, erlaubte Origins für eine Steueroberfläche außerhalb von Loopback explizit angegeben sind und jeder lokale Passwort-Fallback privat hinter der Firewall bleibt.

Das Scope-Modell, in das diese Berechtigungen einfließen, erklärt der Beitrag zu den Operator-Scopes von OpenClaw, die einfachere Alternative für reinen Tailnet-Zugriff beschreibt der Beitrag zu OpenClaw auf Tailscale.

Die Ablehnungscodes lesen

Der Abschnitt zur Fehlerbehebung ordnet jede Ablehnung zu: Eine nicht vertrauenswürdige Quelle bedeutet, dass die Anfrage nicht von einer eingetragenen Proxy-Adresse kam (die Adresse des Proxys ändert sich, wenn Container neu starten); eine Loopback-Quelle bedeutet einen Proxy auf demselben Host ohne das bewusste Opt-in; eine Quelle mit lokalem Interface bedeutet, dass ein Prozess auf dem Gateway-Host Identitäts-Header direkt sendet oder dass der Proxy den Netzwerk-Namespace des Hosts teilt; ein fehlender Benutzer bedeutet, dass der Header fehlt oder falsch benannt ist; ein nicht zugelassener Benutzer bedeutet, dass das Konto authentifiziert ist, aber nicht in der Zulassungsliste steht, und die Dokumentation rät ausdrücklich davon ab, die Zulassungsliste als Workaround zu entfernen; ein nicht erlaubter Origin bedeutet, dass der Browser-Origin die Prüfung der Steueroberfläche nicht bestanden hat. Die Meldung, dass eine Proxy-Authentifizierung erforderlich ist, steht für eine abgewiesene Identität, nicht für einen Netzwerkausfall, und die Lösung ist, sich am Proxy anzumelden, statt Header aus dem Browser zu senden. Die Migration von der Token-Authentifizierung umfasst sechs Schritte: den Proxy konfigurieren, ihn unabhängig testen, die Gateway-Konfiguration aktualisieren, neu starten, den WebSocket aus der Steueroberfläche testen und das Audit ausführen. Einen Vergleich der anderen Muster für den Fernzugriff bietet der Beitrag zum Fernzugriff auf OpenClaw, den Geräteablauf, den die automatische Freigabe ersetzt, beschreibt der Beitrag zur Kopplung in OpenClaw.

Auf Diali

Auf Diali wird jedes Kunden-Gateway über den Ingress der Plattform erreicht, mit einer Laufzeitkonfiguration, die aus dem Dashboard generiert und bei jedem Release ersetzt wird, daher muss kein Kunde diesen Modus von Hand zusammensetzen. Den gehosteten Assistenten beschreibt die Seite zu gehostetem OpenClaw auf Diali, die Grenze um jede Engine beschreibt die Seite zur Sicherheit bei Diali.

• Dem Header nur von eingetragenen Proxy-Adressen vertrauen.
• Loopback-Quellen und Quellen auf eigenen Interfaces werden sicher abgewiesen.
• Der Scopes-Header schränkt ein; Identitätsberechtigungen fügen hinzu, nur für die Sitzung.