Authentifizierung über vertrauenswürdige Proxys

# Wann verwenden

Verwenden Sie den Auth-Modus trusted-proxy, wenn:

• Sie OpenClaw hinter einem identitätsbewussten Proxy betreiben (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 WebSocket-Fehler 1008 unauthorized erhalten, weil Browser keine Tokens in WS-Payloads übergeben können.

# Wann NICHT verwenden

• Wenn Ihr Proxy Benutzer nicht authentifiziert (nur ein TLS-Terminator oder Load Balancer ist).
• Wenn es irgendeinen Pfad zum Gateway gibt, der den Proxy umgeht (Firewall-Lücken, interner Netzwerkzugriff).
• Wenn Sie unsicher sind, ob Ihr Proxy weitergeleitete Header korrekt entfernt/überschreibt.
• Wenn Sie nur persönlichen Zugriff für einen einzelnen Benutzer benötigen (ziehen Sie Tailscale Serve + Loopback für eine einfachere Einrichtung in Betracht).

# Funktionsweise

# Kopplungsverhalten der Control UI

Wenn gateway.auth.mode = "trusted-proxy" aktiv ist und die Anfrage die trusted-proxy-Prüfungen besteht, können WebSocket-Sitzungen der Control UI ohne Geräte-Kopplungsidentität verbunden werden.

Auswirkungen:

• Die Kopplung ist in diesem Modus nicht mehr das primäre Gate für den Zugriff auf die Control UI.
• Ihre Auth-Richtlinie des Reverse Proxy und allowUsers werden zur effektiven Zugriffskontrolle.
• Beschränken Sie den Gateway-Ingress ausschließlich auf vertrauenswürdige Proxy-IPs (gateway.trustedProxies + Firewall).

# Konfiguration

{
  gateway: {
    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default
    bind: "lan",

    // 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: ["[email protected]", "[email protected]"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

# Konfigurationsreferenz

# TLS-Terminierung und HSTS

Verwenden Sie einen 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",
      },
    },
  },
}

# Rollout-Leitfaden

• Beginnen Sie zunächst mit einer kurzen maximalen Dauer (zum Beispiel max-age=300), während Sie den Traffic validieren.
• Erhöhen Sie erst dann auf langlebige Werte (zum Beispiel max-age=31536000), wenn das Vertrauen hoch ist.
• Fügen Sie includeSubDomains nur hinzu, wenn jede Subdomain HTTPS-bereit ist.
• Verwenden Sie Preload nur, wenn Sie die Preload-Anforderungen für Ihren vollständigen Domain-Satz bewusst erfüllen.
• Lokale Entwicklung nur über Loopback profitiert nicht von HSTS.

# Beispiele für Proxy-Einrichtung

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

routes:
  - from: https://openclaw.example.com
    to: http://openclaw-gateway:18789
    policy:
      - allow:
          or:
            - email:
                is: [email protected]
    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

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

Wenn beim Start ein Fehler mixed_trusted_proxy_token angezeigt wird:

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

Loopback-trusted-proxy-Identitäts-Header schlagen weiterhin sicher fehl: Aufrufer vom selben 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. Token-Fallback bleibt im trusted-proxy-Modus absichtlich nicht unterstützt.

# Operator-Scopes-Header

Trusted-proxy-Auth ist ein identitätstragender HTTP-Modus, daher können Aufrufer optional Operator-Scopes mit x-openclaw-scopes deklarieren.

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 den deklarierten Scope-Satz.
• Wenn der Header vorhanden, aber leer ist, deklariert die Anfrage keine Operator-Scopes.
• Wenn der Header fehlt, fallen normale identitätstragende HTTP-APIs auf den standardmäßigen Operator-Default-Scope-Satz zurück.
• Gateway-Auth-Plugin-HTTP-Routen sind standardmäßig enger gefasst: Wenn x-openclaw-scopes fehlt, fällt ihr Laufzeit-Scope auf operator.write zurück.
• HTTP-Anfragen aus Browser-Ursprüngen müssen weiterhin gateway.controlUi.allowedOrigins (oder den bewusst gewählten Host-Header-Fallback-Modus) bestehen, auch nachdem trusted-proxy-Auth erfolgreich war.

Praktische Regel: 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 Schreib-Scope benötigt.

# Sicherheitscheckliste

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

• [ ] Proxy ist der einzige Pfad: Der Gateway-Port ist gegen alles außer Ihrem Proxy per Firewall abgeschirmt.
• [ ] trustedProxies ist minimal: Nur die tatsächlichen IPs Ihres Proxys, keine ganzen Subnetze.
• [ ] Loopback-Proxy-Quelle ist bewusst gewählt: Trusted-Proxy-Authentifizierung schlägt für Anfragen von Loopback-Quellen sicher fehl, sofern gateway.auth.trustedProxy.allowLoopback nicht ausdrücklich für einen Proxy auf demselben Host aktiviert ist.
• [ ] Proxy entfernt Header: Ihr Proxy überschreibt x-forwarded-*-Header von Clients, statt sie anzuhängen.
• [ ] TLS-Terminierung: Ihr Proxy verarbeitet TLS; Benutzer verbinden sich per HTTPS.
• [ ] allowedOrigins ist explizit: Eine Steuerungsoberfläche außerhalb von Loopback verwendet explizite gateway.controlUi.allowedOrigins.
• [ ] allowUsers ist gesetzt (empfohlen): Beschränken Sie den Zugriff auf bekannte Benutzer, statt alle authentifizierten Personen zuzulassen.
• [ ] Keine gemischte Token-Konfiguration: Legen Sie nicht gleichzeitig gateway.auth.token und gateway.auth.mode: "trusted-proxy" fest.
• [ ] Lokaler Passwort-Fallback ist privat: Wenn Sie gateway.auth.password für interne direkte Aufrufer konfigurieren, schirmen Sie den Gateway-Port per Firewall ab, damit Remote-Clients außerhalb des Proxys ihn nicht direkt erreichen können.

# Sicherheits-Audit

openclaw security audit meldet Trusted-Proxy-Authentifizierung mit einem Befund der Schwere kritisch. Das ist beabsichtigt: Es erinnert Sie daran, dass Sie die Sicherheit an Ihre Proxy-Einrichtung delegieren.

Das Audit prüft auf:

• Grundlegende Warnung/kritische Erinnerung gateway.trusted_proxy_auth
• Fehlende trustedProxies-Konfiguration
• Fehlende userHeader-Konfiguration
• Leere allowUsers (lässt jeden authentifizierten Benutzer zu)
• Aktiviertes allowLoopback für Proxy-Quellen auf demselben Host
• Platzhalter- oder fehlende Browser-Origin-Richtlinie auf exponierten Oberflächen der Steuerungsoberfläche

# Fehlerbehebung

# Migration von Token-Authentifizierung

Wenn Sie von Token-Authentifizierung zu Trusted-Proxy wechseln:

# Verwandte Themen

• Konfiguration — Konfigurationsreferenz
• Remote-Zugriff — andere Muster für Remote-Zugriff
• Sicherheit — vollständiger Sicherheitsleitfaden
• Tailscale — einfachere Alternative für Zugriff nur innerhalb des Tailnet