Authentifizierung über vertrauenswürdige Proxys

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Wann verwenden

• 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

• 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: ["nick@example.com", "admin@company.org"],

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

​

Konfigurationsreferenz

​

TLS-Terminierung und HSTS

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: nick@example.com
    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

• 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.

​

Operator-Scopes-Header

• 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 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.

​

Sicherheitscheckliste

• 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

• 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

​

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