OpenClaw Trusted Proxy Auth: Sicher konfigurieren

Kennst du das? Du hast bereits ein ausgereiftes Identity-Management mit einem Reverse Proxy aufgebaut, aber dein neues Tool verlangt trotzdem nach eigenen Tokens oder einer separaten Anmeldung. Das ist nicht nur nervig für den Workflow, sondern führt oft zu Problemen bei WebSockets, weil Browser Tokens in diesen Payloads nicht immer sauber übertragen.

Hier kommt der trusted-proxy Modus ins Spiel. Damit delegierst du die Authentifizierung komplett an deinen Proxy und machst dir das Leben leichter.

Trusted Proxy Auth

⚠️ Sicherheitsrelevante Funktion. Dieser Modus delegiert die Authentifizierung vollständig an deinen Reverse Proxy. Eine Fehlkonfiguration kann dein Gateway für unbefugten Zugriff öffnen. Lies diese Seite sorgfältig durch, bevor du die Funktion aktivierst.

Wann du es nutzen solltest

Nutze den trusted-proxy Auth-Modus, wenn:

• Du OpenClaw hinter einem Identity-Aware Proxy betreibst (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + Forward Auth).
• Dein Proxy die gesamte Authentifizierung übernimmt und die Benutzeridentität über Header weitergibt.
• Du in einer Kubernetes- oder Container-Umgebung arbeitest, in der der Proxy der einzige Weg zum Gateway ist.
• Du WebSocket 1008 unauthorized Fehler erhältst, weil Browser keine Tokens in WS-Payloads übertragen können.

Wann du es NICHT nutzen solltest

• Wenn dein Proxy Benutzer nicht authentifiziert (sondern nur als TLS-Terminator oder Load Balancer fungiert).
• Wenn es irgendeinen Weg zum Gateway gibt, der den Proxy umgeht (Firewall-Lücken, interner Netzwerkzugriff).
• Wenn du unsicher bist, ob dein Proxy weitergeleitete Header korrekt bereinigt oder überschreibt.
• Wenn du nur persönlichen Einzelbenutzer-Zugriff benötigst (nutze hierfür lieber Tailscale Serve + Loopback für ein einfacheres Setup).

Wie es funktioniert

1. Dein Reverse Proxy authentifiziert die Benutzer (OAuth, OIDC, SAML, etc.).
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 kommt (konfiguriert in gateway.trustedProxies).
4. OpenClaw extrahiert die Benutzeridentität aus dem konfigurierten Header.
5. Wenn alles passt, wird die Anfrage autorisiert.

Control UI Pairing-Verhalten

Wenn gateway.auth.mode = "trusted-proxy" aktiv ist und die Anfrage die Trusted-Proxy-Prüfungen besteht, können sich Control UI WebSocket-Sessions ohne Device-Pairing-Identität verbinden.

Auswirkungen:

• Pairing ist in diesem Modus nicht mehr die primäre Zugangskontrolle für die Control UI.
• Die Auth-Policy deines Reverse Proxys und allowUsers werden zu den effektiven Zugriffskontrollen.
• Halte den Gateway-Ingress strikt auf vertrauenswürdige Proxy-IPs beschränkt (gateway.trustedProxies + Firewall).

Konfiguration

{
  gateway: {
    // Use loopback for same-host proxy setups; use lan/custom for remote proxy hosts
    bind: "loopback",

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

Falls gateway.bind auf loopback steht, füge eine Loopback-Proxy-Adresse in gateway.trustedProxies hinzu (127.0.0.1, ::1 oder ein entsprechendes Loopback-CIDR).

Konfigurations-Referenz

Feld	Erforderlich	Beschreibung
gateway.trustedProxies	Ja	Array von Proxy-IP-Adressen, denen vertraut wird. Anfragen von anderen IPs werden abgelehnt.
gateway.auth.mode	Ja	Muss "trusted-proxy" sein.
gateway.auth.trustedProxy.userHeader	Ja	Name des Headers, der die authentifizierte Benutzeridentität enthält.
gateway.auth.trustedProxy.requiredHeaders	Nein	Zusätzliche Header, die vorhanden sein müssen, damit der Anfrage vertraut wird.
gateway.auth.trustedProxy.allowUsers	Nein	Allowlist von Benutzeridentitäten. Leer bedeutet, dass alle authentifizierten Benutzer erlaubt sind.

TLS-Terminierung und HSTS

Nutze einen TLS-Terminierungspunkt und wende HSTS dort an.

Empfohlenes Muster: Proxy TLS-Terminierung

Wenn dein Reverse Proxy HTTPS für https://control.example.com übernimmt, setze Strict-Transport-Security am Proxy für diese Domain.

• Gute Wahl für Deployments, die über das Internet erreichbar sind.
• Zertifikat und HTTP-Hardening-Policy bleiben an einem zentralen Ort.
• OpenClaw kann auf Loopback-HTTP hinter dem Proxy bleiben.

Beispiel für einen Header-Wert:

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

Gateway TLS-Terminierung

Falls OpenClaw HTTPS direkt selbst bereitstellt (kein TLS-terminierender Proxy), konfiguriere:

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

strictTransportSecurity akzeptiert einen String als Header-Wert oder false, um es explizit zu deaktivieren.

Hinweise zum Rollout

• Starte zuerst mit einer kurzen Max-Age (zum Beispiel max-age=300), während du den Traffic validierst.
• Erhöhe erst auf langfristige Werte (zum Beispiel max-age=31536000), wenn alles sicher läuft.
• Füge includeSubDomains nur hinzu, wenn jede Subdomain für HTTPS bereit ist.
• Nutze Preload nur, wenn du die Preload-Anforderungen für dein gesamtes Domain-Set bewusst erfüllst.
• Lokale Entwicklung über Loopback profitiert nicht von HSTS.

Proxy-Setup-Beispiele

Pomerium

Pomerium übergibt die Identität in x-pomerium-claim-email (oder anderen Claim-Headern) und ein JWT in x-pomerium-jwt-assertion.

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

Pomerium Konfigurations-Schnipsel:

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

Caddy mit dem caddy-security Plugin kann Benutzer authentifizieren und Identitäts-Header weitergeben.

{
  gateway: {
    bind: "lan",
    trustedProxies: ["127.0.0.1"], // Caddy's IP (if on same host)
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

Caddyfile-Schnipsel:

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

oauth2-proxy authentifiziert Benutzer und übergibt die Identität in x-auth-request-email.

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-auth-request-email",
      },
    },
  },
}

nginx Konfigurations-Schnipsel:

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"], // Traefik container IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

Gemischte Token-Konfiguration

OpenClaw lehnt uneindeutige Konfigurationen ab, bei denen sowohl ein gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN) als auch der trusted-proxy Modus gleichzeitig aktiv sind. Solche Setups können dazu führen, dass Loopback-Anfragen fälschlicherweise über den falschen Auth-Pfad authentifiziert werden.

Falls du beim Start einen mixed_trusted_proxy_token Fehler siehst:

• Entferne das geteilte Token, wenn du den Trusted-Proxy-Modus nutzt, oder
• Wechsle gateway.auth.mode zu "token", falls du Token-basierte Auth beabsichtigst.

Loopback Trusted-Proxy-Auth ist standardmäßig restriktiv: Aufrufer vom selben Host müssen die konfigurierten Identitäts-Header über einen vertrauenswürdigen Proxy liefern, anstatt automatisch authentifiziert zu werden.

Sicherheits-Checkliste

Bevor du Trusted-Proxy-Auth aktivierst, prüfe folgendes:

• Proxy ist der einzige Weg: Der Gateway-Port ist per Firewall vor allem geschützt, außer vor deinem Proxy.
• trustedProxies ist minimal: Nur deine tatsächlichen Proxy-IPs sind eingetragen, keine ganzen Subnetze.
• Proxy bereinigt Header: Dein Proxy überschreibt x-forwarded-* Header von Clients (anstatt sie anzuhängen).
• TLS-Terminierung: Dein Proxy übernimmt TLS; Benutzer verbinden sich via HTTPS.
• allowUsers ist gesetzt (empfohlen): Beschränke den Zugriff auf bekannte Benutzer, anstatt jeden Authentifizierten zuzulassen.
• Keine gemischte Token-Konfig: Setze nicht gleichzeitig gateway.auth.token und gateway.auth.mode: "trusted-proxy".

Sicherheits-Audit

openclaw security audit wird Trusted-Proxy-Auth mit dem Schweregrad Critical markieren. Das ist Absicht — es dient als Erinnerung daran, dass du die Sicherheit an dein Proxy-Setup delegierst.

Das Audit prüft auf:

• Fehlende trustedProxies oder userHeader Konfiguration.
• Leere allowUsers Listen (erlaubt jeden authentifizierten Benutzer).

Fehlerbehebung

”trusted_proxy_untrusted_source”

Die Anfrage kam nicht von einer IP aus gateway.trustedProxies. Prüfe:

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

”trusted_proxy_user_missing”

Der Benutzer-Header war leer oder fehlte. Prüfe:

• Ist dein Proxy so konfiguriert, dass er Identitäts-Header weitergibt?
• Ist der Header-Name korrekt geschrieben? (Groß-/Kleinschreibung ist egal, aber die Schreibweise zählt).
• Ist der Benutzer am Proxy tatsächlich authentifiziert?

“trusted_proxy_missing_header_*”

Ein erforderlicher Header war nicht vorhanden. Prüfe:

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

”trusted_proxy_user_not_allowed”

Der Benutzer ist authentifiziert, aber nicht in allowUsers gelistet. Füge ihn hinzu oder entferne die Allowlist.

WebSocket schlägt weiterhin fehl

Stelle sicher, dass dein Proxy:

• WebSocket-Upgrades unterstützt (Upgrade: websocket, Connection: upgrade).
• Die Identitäts-Header auch bei WebSocket-Upgrade-Anfragen mitschickt (nicht nur bei HTTP).
• Keinen separaten Auth-Pfad für WebSocket-Verbindungen hat.

Migration von Token-Auth

Wenn du von Token-Auth zu Trusted-Proxy wechselst:

1. Konfiguriere deinen Proxy für die Benutzerauthentifizierung und Header-Weitergabe.
2. Teste das Proxy-Setup unabhängig (z. B. mit curl und manuellen Headern).
3. Aktualisiere die OpenClaw-Konfig auf Trusted-Proxy-Auth.
4. Starte das Gateway neu.
5. Teste die WebSocket-Verbindungen über die Control UI.
6. Führe openclaw security audit aus und prüfe die Ergebnisse.

Verwandte Themen

• Security — Vollständiger Sicherheits-Leitfaden
• Configuration — Konfigurations-Referenz
• Remote Access — Andere Muster für den Fernzugriff
• Tailscale — Einfachere Alternative für reinen Tailnet-Zugriff

Nächste Schritte

• Schau dir den Security Guide an, um dein Setup weiter abzusichern.
• Erfahre mehr über die Konfigurations-Optionen für das Gateway.

AI Setup Assistant