Authentifizierung über vertrauenswürdigen Proxy

​

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 Containerumgebung befinden, in der der Proxy der einzige Pfad zum Gateway ist.
• Sie WebSocket-Fehler vom Typ 1008 unauthorized erhalten, weil Browser keine Tokens in WS-Payloads übergeben können.

​

Wann NICHT verwenden

• Wenn Ihr Proxy Benutzer nicht authentifiziert (nur TLS-Terminierung oder Load Balancer).
• 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 Einzelbenutzerzugriff benötigen (erwägen Sie Tailscale Serve + Loopback für eine einfachere Einrichtung).

​

Funktionsweise

​

Pairing-Verhalten der Control UI

• Gerätelose Control-UI-WebSocket-Sitzungen verbinden sich, erhalten aber standardmäßig keine Operator-Scopes. OpenClaw leert die angeforderte Scope-Liste auf [], sodass eine Sitzung, die nicht an ein genehmigtes gekoppeltes Gerät/Token gebunden ist, keine Berechtigungen selbst deklarieren kann.
• Wenn Methoden nach einer erfolgreichen WebSocket-Verbindung mit missing scope fehlschlagen, verwenden Sie HTTPS, damit der Browser eine Geräteidentität erzeugen und das Pairing abschließen kann. Siehe unsicheres HTTP für die Control UI.
• Nur für den Notfall: gateway.controlUi.dangerouslyDisableDeviceAuth=true behält angeforderte Scopes auch ohne Geräteidentität bei. Dies ist eine schwerwiegende Sicherheitsherabstufung; machen Sie sie schnell rückgängig. Siehe unsicheres HTTP für die Control UI.

• Wenn Ihr Proxy x-openclaw-scopes bei der Control-UI-WebSocket-Upgrade-Anfrage sendet, begrenzt OpenClaw die Sitzungs-Scopes auf die Schnittmenge aus den angeforderten Scopes und den deklarierten Scopes. Dieser Header gewährt keine Scopes; er schränkt nur ein, was die Sitzung halten kann.

• Pairing ist in diesem Modus nicht mehr die primäre Hürde für den Zugriff auf die Control UI.
• Die Authentifizierungsrichtlinie Ihres Reverse Proxys 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-Empfehlungen

• Beginnen Sie zuerst mit einer kurzen maximalen Gültigkeitsdauer (zum Beispiel max-age=300), während Sie den Traffic validieren.
• Erhöhen Sie erst auf langlebige Werte (zum Beispiel max-age=31536000), wenn die Sicherheit 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 absichtlich erfüllen.
• Reine Loopback-Entwicklung lokal 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 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, fallen normale identitätstragende HTTP-APIs auf die standardmäßige Operator-Default-Scope-Menge 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 bestehen (oder den bewusst gewählten Host-Header-Fallback-Modus), auch nachdem die Trusted-Proxy-Authentifizierung erfolgreich war.
• Für WebSocket-Sitzungen der Control UI ist x-openclaw-scopes eine Scope-Obergrenze, wenn der Header in der Upgrade-Anfrage vorhanden ist. Ein leerer Wert ergibt keine Scopes.

​

Sicherheits-Checkliste

• Proxy ist der einzige Pfad: Der Gateway-Port ist per Firewall vor allem außer Ihrem Proxy geschützt.
• trustedProxies ist minimal: Nur Ihre tatsächlichen Proxy-IPs, keine ganzen Subnetze.
• Loopback-Proxy-Quelle ist beabsichtigt: Trusted-Proxy-Authentifizierung verweigert Loopback-Quellanfragen sicher, sofern gateway.auth.trustedProxy.allowLoopback nicht explizit 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 übernimmt TLS; Benutzer verbinden sich per HTTPS.
• allowedOrigins ist explizit: Nicht-Loopback-Control-UI verwendet explizite gateway.controlUi.allowedOrigins.
• allowUsers ist gesetzt (empfohlen): Beschränken Sie den Zugriff auf bekannte Benutzer, statt beliebige authentifizierte Benutzer zuzulassen.
• Keine gemischte Token-Konfiguration: Setzen Sie nicht gleichzeitig gateway.auth.token und gateway.auth.mode: "trusted-proxy".
• Lokaler Passwort-Fallback ist privat: Wenn Sie gateway.auth.password für interne direkte Aufrufer konfigurieren, schützen Sie den Gateway-Port per Firewall, damit entfernte Nicht-Proxy-Clients ihn nicht direkt erreichen können.

​

Sicherheitsaudit

• Basiswarnung/kritische Erinnerung gateway.trusted_proxy_auth
• Fehlende trustedProxies-Konfiguration
• Fehlende userHeader-Konfiguration
• Leere allowUsers (erlaubt jeden authentifizierten Benutzer)
• Aktiviertes allowLoopback für Proxy-Quellen auf demselben Host
• Wildcard- oder fehlende Browser-Origin-Richtlinie auf exponierten Control-UI-Oberflächen

​

Fehlerbehebung

​

Migration von Token-Authentifizierung

​

Verwandte Themen

• Konfiguration — Konfigurationsreferenz
• Remotezugriff — andere Remotezugriffsmuster
• Sicherheit — vollständiger Sicherheitsleitfaden
• Tailscale — einfachere Alternative für reinen Tailnet-Zugriff