​

Trusted Proxy Auth

⚠️ Sicherheitskritische Funktion. In diesem Modus wird die Authentifizierung vollständig an Ihren Reverse Proxy delegiert. Eine Fehlkonfiguration kann Ihr Gateway unbefugtem Zugriff aussetzen. Lesen Sie diese Seite sorgfältig, bevor Sie sie aktivieren.

​

Wann verwenden

• Sie OpenClaw hinter einem identitätsbewussten Proxy ausführen (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 Container-Umgebung befinden, in der der Proxy der einzige Pfad zum Gateway ist
• Sie auf WebSocket-Fehler vom Typ 1008 unauthorized stoßen, weil Browser keine Tokens in WS-Payloads übergeben können

​

Wann NICHT verwenden

• Wenn Ihr Proxy Benutzer nicht authentifiziert (nur TLS-Terminator oder Load Balancer)
• Wenn es irgendeinen Pfad zum Gateway gibt, der den Proxy umgeht (Firewall-Lücken, interner Netzwerkzugriff)
• Wenn Sie nicht sicher sind, ob Ihr Proxy weitergeleitete Header korrekt entfernt/überschreibt
• Wenn Sie nur persönlichen Einzelbenutzerzugriff benötigen (für ein einfacheres Setup sollten Sie Tailscale Serve + loopback in Betracht ziehen)

​

So funktioniert es

1. Ihr Reverse Proxy authentifiziert Benutzer (OAuth, OIDC, SAML usw.)
2. Der Proxy fügt einen Header mit der authentifizierten Benutzeridentität hinzu (z. B. x-forwarded-user: nick@example.com)
3. OpenClaw prüft, ob die Anfrage von einer vertrauenswürdigen Proxy-IP stammt (konfiguriert in gateway.trustedProxies)
4. OpenClaw extrahiert die Benutzeridentität aus dem konfigurierten Header
5. Wenn alles passt, wird die Anfrage autorisiert

​

Pairing-Verhalten der Control UI

• Pairing ist in diesem Modus nicht mehr die primäre Schranke für den Zugriff auf die Control UI.
• Ihre Reverse-Proxy-Auth-Richtlinie und allowUsers werden zur effektiven Zugriffskontrolle.
• Halten Sie den Gateway-Ingress strikt auf vertrauenswürdige Proxy-IPs beschränkt (gateway.trustedProxies + Firewall).

​

Konfiguration

{
  gateway: {
    // Trusted-Proxy-Auth erwartet Anfragen von einer vertrauenswürdigen Nicht-Loopback-Proxy-Quelle
    bind: "lan",

    // KRITISCH: Fügen Sie hier nur die IP(s) 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-Verifizierung)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Optional: auf bestimmte Benutzer beschränken (leer = alle zulassen)
        allowUsers: ["nick@example.com", "admin@company.org"],
      },
    },
  },
}

• Trusted-Proxy-Auth lehnt Anfragen von loopback-Quellen (127.0.0.1, ::1, loopback-CIDRs) ab.
• Reverse Proxys auf demselben Host über loopback erfüllen Trusted-Proxy-Auth nicht.
• Für Proxy-Setups über loopback auf demselben Host verwenden Sie stattdessen Token-/Passwort-Auth oder routen Sie über eine vertrauenswürdige Nicht-Loopback-Proxy-Adresse, die OpenClaw verifizieren kann.
• Nicht-Loopback-Bereitstellungen der Control UI benötigen weiterhin explizite gateway.controlUi.allowedOrigins.

​

Konfigurationsreferenz

​

TLS-Terminierung und HSTS

​

Empfohlenes Muster: TLS-Terminierung am Proxy

• Geeignet für internetseitig erreichbare Bereitstellungen.
• Hält Zertifikate und HTTP-Härtungsrichtlinien an einem Ort zusammen.
• OpenClaw kann hinter dem Proxy auf loopback-HTTP bleiben.

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

​

TLS-Terminierung am Gateway

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

​

Hinweise zum Rollout

• Beginnen Sie zunächst mit einer kurzen Max-Age-Zeit (zum Beispiel max-age=300), während Sie den Datenverkehr validieren.
• Erhöhen Sie auf langlebige Werte (zum Beispiel max-age=31536000) erst, wenn Sie hohe Sicherheit haben.
• Fügen Sie includeSubDomains nur hinzu, wenn jede Subdomain für HTTPS bereit ist.
• Verwenden Sie Preload nur, wenn Sie die Preload-Anforderungen für Ihre gesamte Domainmenge bewusst erfüllen.
• Rein lokale Entwicklung mit loopback profitiert nicht von HSTS.

​

Beispiele für Proxy-Setups

​

Pomerium

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

​

Caddy mit OAuth

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // IP von Caddy/Sidecar-Proxy
    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}
    }
}

​

nginx + oauth2-proxy

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

​

Traefik mit Forward Auth

{
  gateway: {
    bind: "lan",
    trustedProxies: ["172.17.0.1"], // IP des Traefik-Containers
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

Gemischte Token-Konfiguration

• Entfernen Sie das gemeinsame Token, wenn Sie den Modus trusted-proxy verwenden, oder
• wechseln Sie gateway.auth.mode zu "token", wenn Sie tokenbasierte Authentifizierung beabsichtigen.

​

Header für Operator-Scopes

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

• 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, greifen normale identitätstragende HTTP-APIs auf die Standardmenge der Operator-Default-Scopes zurück.
• Gateway-auth-Plugin-HTTP-Routen sind standardmäßig enger: Wenn x-openclaw-scopes fehlt, fällt ihr Laufzeit-Scope auf operator.write zurück.
• HTTP-Anfragen aus dem Browser müssen auch nach erfolgreicher Trusted-Proxy-Auth weiterhin gateway.controlUi.allowedOrigins bestehen (oder den bewusst aktivierten Host-Header-Fallback-Modus).

• Senden Sie x-openclaw-scopes explizit, wenn eine Trusted-Proxy-Anfrage enger sein soll als die Standardwerte oder wenn eine Gateway-auth-Plugin-Route etwas Stärkeres als den Write-Scope benötigt.

​

Sicherheits-Checkliste

• Der Proxy ist der einzige Pfad: Der Gateway-Port ist gegenüber allem außer Ihrem Proxy durch eine Firewall geschützt
• trustedProxies ist minimal: Nur die tatsächlichen IPs Ihres Proxys, nicht ganze Subnetze
• Keine Proxy-Quelle über loopback: Trusted-Proxy-Auth schlägt bei Anfragen von loopback-Quellen sicher fehl
• Proxy entfernt Header: Ihr Proxy überschreibt (statt anzuhängen) x-forwarded-*-Header von Clients
• TLS-Terminierung: Ihr Proxy verarbeitet TLS; Benutzer verbinden sich über HTTPS
• allowedOrigins ist explizit: Nicht-Loopback-Control-UI verwendet explizite gateway.controlUi.allowedOrigins
• allowUsers ist gesetzt (empfohlen): Auf bekannte Benutzer beschränken, statt jeden authentifizierten Benutzer zuzulassen
• Keine gemischte Token-Konfiguration: Setzen Sie nicht gleichzeitig gateway.auth.token und gateway.auth.mode: "trusted-proxy"

​

Security Audit

• Basiswarnung/-erinnerung gateway.trusted_proxy_auth mit warning/critical
• Fehlende Konfiguration von trustedProxies
• Fehlende Konfiguration von userHeader
• Leeres allowUsers (erlaubt jeden authentifizierten Benutzer)
• Wildcard- oder fehlende Browser-Origin-Richtlinie auf exponierten Oberflächen der Control UI

​

Fehlerbehebung

​

trusted_proxy_untrusted_source

• Ist die Proxy-IP korrekt? (Docker-Container-IPs können sich ändern)
• Befindet sich ein Load Balancer vor Ihrem Proxy?
• Verwenden Sie docker inspect oder kubectl get pods -o wide, um die tatsächlichen IPs zu finden

​

trusted_proxy_loopback_source

• Verbindet sich der Proxy von 127.0.0.1 / ::1?
• Versuchen Sie, Trusted-Proxy-Auth mit einem Reverse Proxy über loopback auf demselben Host zu verwenden?

• Verwenden Sie Token-/Passwort-Auth für Proxy-Setups über loopback auf demselben Host, oder
• routen Sie über eine vertrauenswürdige Nicht-Loopback-Proxy-Adresse und behalten Sie diese IP in gateway.trustedProxies.

​

trusted_proxy_user_missing

• Ist Ihr Proxy so konfiguriert, dass er Identitäts-Header weitergibt?
• Ist der Header-Name korrekt? (Groß-/Kleinschreibung spielt keine Rolle, die Schreibweise aber schon)
• Ist der Benutzer am Proxy tatsächlich authentifiziert?

​

trusted*proxy_missing_header*\*

• Ihre Proxy-Konfiguration für diese spezifischen Header
• Ob Header irgendwo in der Kette entfernt werden

​

trusted_proxy_user_not_allowed

​

trusted_proxy_origin_not_allowed

• gateway.controlUi.allowedOrigins enthält den exakten Browser-Origin
• Sie verlassen sich nicht auf Wildcard-Origins, außer wenn Sie absichtlich ein Allow-all-Verhalten möchten
• Wenn Sie bewusst den Host-Header-Fallback-Modus verwenden, ist gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true ausdrücklich gesetzt

​

WebSocket schlägt weiterhin fehl

• WebSocket-Upgrades unterstützt (Upgrade: websocket, Connection: upgrade)
• die Identitäts-Header bei WebSocket-Upgrade-Anfragen weitergibt (nicht nur bei HTTP)
• keinen separaten Auth-Pfad für WebSocket-Verbindungen hat

​

Migration von Token-Auth

1. Konfigurieren Sie Ihren Proxy so, dass er Benutzer authentifiziert und Header weitergibt
2. Testen Sie das Proxy-Setup unabhängig (curl mit Headern)
3. Aktualisieren Sie die OpenClaw-Konfiguration mit Trusted-Proxy-Auth
4. Starten Sie das Gateway neu
5. Testen Sie WebSocket-Verbindungen aus der Control UI
6. Führen Sie openclaw security audit aus und prüfen Sie die Befunde

​

Verwandt

• Security — vollständiger Sicherheitsleitfaden
• Configuration — Konfigurationsreferenz
• Remote Access — andere Muster für Remote-Zugriff
• Tailscale — einfachere Alternative für Tailnet-only-Zugriff