Authentifizierung über vertrauenswürdigen Proxy

​

Verwendung

• Sie betreiben OpenClaw hinter einem identitätsbewussten Proxy (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + Forward Auth).
• Ihr Proxy übernimmt die gesamte Authentifizierung und übermittelt die Benutzeridentität über Header.
• Sie verwenden eine Kubernetes- oder Containerumgebung, in der der Proxy der einzige Pfad zum Gateway ist.
• WebSocket-Fehler vom Typ 1008 unauthorized treten auf, weil Browser keine Token in WS-Nutzdaten übermitteln können.

​

Nicht verwenden

• Ihr Proxy authentifiziert keine Benutzer, sondern dient lediglich als TLS-Terminator oder Lastverteiler.
• Es gibt einen Pfad zum Gateway, der den Proxy umgeht, etwa durch Firewall-Lücken oder internen Netzwerkzugriff.
• Sie sind nicht sicher, ob Ihr Proxy weitergeleitete Header ordnungsgemäß entfernt oder überschreibt.
• Sie benötigen nur persönlichen Einzelbenutzerzugriff; erwägen Sie stattdessen Tailscale Serve + Loopback.

​

Funktionsweise

​

Konfiguration

{
  gateway: {
    // Bei Trusted-Proxy-Authentifizierung darf die Quell-IP des Proxys standardmäßig keine Loopback-Adresse sein
    bind: "lan",

    // KRITISCH: Fügen Sie hier ausschließlich die IP-Adresse(n) 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-Überprüfung)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

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

        // Optional: nach ausdrücklicher Aktivierung einen Loopback-Proxy auf demselben Host zulassen
        allowLoopback: false,

        // Optional: authentifizierten Proxy-Benutzern die Registrierung neuer Browsergeräte erlauben
        deviceAutoApprove: {
          enabled: false,
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
      },
    },
  },
}

​

Konfigurationsreferenz

​

Automatische Gerätegenehmigung

{
  gateway: {
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        allowUsers: ["operator@example.com"],
        deviceAutoApprove: {
          enabled: true,
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
      },
    },
  },
}

1. Der WebSocket muss über die Methode trusted-proxy mit einer nicht leeren Benutzeridentität authentifiziert worden sein, die allowUsers erfüllt, wenn eine Zulassungsliste konfiguriert ist. Verbindungen über Token, Passwort, Tailscale oder ohne Authentifizierung verwenden diese Richtlinie niemals.
2. Nur ein neues Browsergerät der Control UI oder von WebChat kann automatisch genehmigt werden. Jede Anfrage für ein vorhandenes Gerät, einschließlich einer Erweiterung der Berechtigungsbereiche, bleibt zur manuellen Genehmigung mit openclaw devices approve <requestId> ausstehend.
3. Das Gerät wird mit der Rolle operator genehmigt. Wenn die Verbindungsanfrage Berechtigungsbereiche enthält, entspricht die Gewährung exakt der Schnittmenge aus den angeforderten Berechtigungsbereichen und deviceAutoApprove.scopes. Lässt die Anfrage die Berechtigungsbereiche aus, wird die konfigurierte Liste gewährt. Wenn diese Liste nicht angegeben ist, werden standardmäßig operator.read, operator.write und operator.approvals verwendet. Die resultierende Gewährung wird anschließend zusätzlich durch den Proxy-Header x-openclaw-scopes der Verbindung begrenzt, sofern dieser vorhanden ist. Dadurch begrenzt ein Proxy, der die Berechtigungsbereiche eines Benutzers einschränkt, auch die dauerhafte Gerätegewährung und nicht nur die Sitzung; ein vorhandener, aber leerer Header gewährt keine Berechtigungsbereiche. Diese Begrenzung gilt auch, wenn der Client seine eigene Liste der Berechtigungsbereiche auslässt.
4. operator.admin ist nur zulässig, wenn es ausdrücklich in deviceAutoApprove.scopes aufgeführt wird. Ist es aufgeführt, kann jeder über den Proxy authentifizierte Benutzer vollständige Administratorrechte für ein neues Browsergerät anfordern und automatisch erhalten. Anfragen ohne Berechtigungsbereiche erhalten automatisch vollständige Administratorrechte. openclaw security audit meldet den KRITISCHEN Befund gateway.trusted_proxy_device_auto_approve_admin, und der Gateway protokolliert beim Start einmalig eine Warnung. Bevorzugen Sie die manuelle Administratorgenehmigung mit openclaw devices approve oder openclaw devices rotate, bis identitätsspezifische Rollen verfügbar sind.

​

Kopplungsverhalten der Control UI

• Control-UI-WebSocket-Sitzungen ohne Gerät stellen eine Verbindung her, erhalten standardmäßig jedoch keine Operator-Berechtigungsbereiche. OpenClaw leert die Liste der angeforderten Berechtigungsbereiche zu [], sodass eine Sitzung, die nicht an ein genehmigtes gekoppeltes Gerät oder 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 die Kopplung abschließen kann. Siehe Unsicheres HTTP der Control UI.
• Ältere Konfigurationen, die noch den außer Betrieb genommenen Schlüssel gateway.controlUi.dangerouslyDisableDeviceAuth=true enthalten, verwenden die begrenzte Upgrade-Migration der Control UI.

• Die Kopplung ist nicht mehr die primäre Zugriffssperre für den gerätelosen Zugriff auf die Control UI. Wenn deviceAutoApprove.enabled wahr ist, wird die Proxy-Identität außerdem zur Genehmigungssperre für die Registrierung neuer Browsergeräte.
• Die Authentifizierungsrichtlinie Ihres Reverse-Proxys und allowUsers bilden die effektive Zugriffskontrolle.
• Beschränken Sie den Gateway-Eingang ausschließlich auf vertrauenswürdige Proxy-IP-Adressen (gateway.trustedProxies + Firewall).

​

Header für Operator-Berechtigungsbereiche

• 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 Menge an Berechtigungsumfängen.
• Wenn der Header vorhanden, aber leer ist, deklariert die Anfrage keine Operator-Berechtigungsumfänge.
• Wenn der Header fehlt, greifen normale identitätstragende HTTP-APIs auf die standardmäßige Menge an Operator-Berechtigungsumfängen zurück (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Durch Gateway-Authentifizierung geschützte Plugin-HTTP-Routen sind standardmäßig restriktiver: Wenn x-openclaw-scopes fehlt, greift ihr Laufzeit-Berechtigungsumfang ausschließlich auf operator.write zurück.
• HTTP-Anfragen mit Browser-Ursprung müssen auch nach erfolgreicher Trusted-Proxy-Authentifizierung weiterhin gateway.controlUi.allowedOrigins (oder den bewusst aktivierten Host-Header-Fallbackmodus) passieren.

​

TLS-Terminierung und HSTS

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

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

​

Hinweise zur Einführung

• Beginnen Sie zunächst mit einer kurzen maximalen Gültigkeitsdauer (zum Beispiel max-age=300), während Sie den Datenverkehr validieren.
• Erhöhen Sie sie erst dann auf langfristige Werte (zum Beispiel max-age=31536000), wenn eine hohe Sicherheit besteht.
• Fügen Sie includeSubDomains nur hinzu, wenn jede Subdomain für HTTPS bereit ist.
• Verwenden Sie Preloading nur, wenn Sie die Preload-Anforderungen für Ihre gesamte Domainmenge bewusst erfüllen.
• Eine ausschließlich über Loopback erreichbare lokale Entwicklungsumgebung profitiert nicht von HSTS.

​

Beispiele für die Proxy-Einrichtung

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

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

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

​

Gemischte Token-Konfiguration

• Entfernen Sie das gemeinsam verwendete Token, wenn Sie den Trusted-Proxy-Modus verwenden, oder
• ändern Sie gateway.auth.mode in "token", wenn Sie eine tokenbasierte Authentifizierung verwenden möchten.

​

Sicherheitscheckliste

• Der Proxy ist der einzige Pfad: Der Gateway-Port ist durch eine Firewall für alles außer Ihrem Proxy gesperrt.
• trustedProxies ist minimal: Nur die tatsächlichen IP-Adressen Ihres Proxys, keine ganzen Subnetze.
• Eine Loopback-Proxyquelle ist beabsichtigt: Die Trusted-Proxy-Authentifizierung schlägt bei Anfragen aus einer Loopback-Quelle sicher fehl, sofern gateway.auth.trustedProxy.allowLoopback nicht ausdrücklich für einen Proxy auf demselben Host aktiviert ist.
• Der Proxy entfernt Header: Ihr Proxy überschreibt von Clients stammende x-forwarded-*-Header, statt sie anzuhängen.
• TLS-Terminierung: Ihr Proxy verarbeitet TLS; Benutzer stellen die Verbindung über HTTPS her.
• allowedOrigins ist ausdrücklich festgelegt: Eine nicht über Loopback erreichbare Control UI verwendet ausdrücklich gateway.controlUi.allowedOrigins.
• allowUsers ist festgelegt (empfohlen): Beschränken Sie den Zugriff auf bekannte Benutzer, statt jeden authentifizierten Benutzer zuzulassen.
• Keine gemischte Token-Konfiguration: Legen Sie nicht sowohl gateway.auth.token als auch gateway.auth.mode: "trusted-proxy" fest.
• Der lokale Passwort-Fallback ist privat: Wenn Sie gateway.auth.password für interne direkte Aufrufer konfigurieren, schützen Sie den Gateway-Port durch eine Firewall, damit entfernte Clients außerhalb des Proxys nicht direkt darauf zugreifen können.
• Die automatische Gerätegenehmigung ist beabsichtigt: Wenn deviceAutoApprove.enabled wahr ist, behandeln Sie die Sicherheit des Reverse-Proxy-Kontos als Grenze für die Geräteregistrierung und halten Sie die Liste der gewährten Berechtigungsumfänge auf Nicht-Administratorrechte beschränkt und minimal.

​

Sicherheitsprüfung

• Grundlegende gateway.trusted_proxy_auth-Warnung bzw. kritische Erinnerung.
• Fehlende trustedProxies-Konfiguration.
• Fehlende userHeader-Konfiguration.
• Leeres allowUsers (lässt jeden authentifizierten Benutzer zu).
• Aktiviertes allowLoopback für Proxyquellen auf demselben Host.
• Aktivierte automatische Genehmigung von Browsergeräten (delegiert die Kopplung neuer Geräte an die Proxy-Identität).

​

Fehlerbehebung

​

Migration von Token-Authentifizierung

​

Verwandte Themen

• Konfiguration — Konfigurationsreferenz
• Operator-Scopes — Rollen, Scopes und Genehmigungsprüfungen
• Remotezugriff — weitere Muster für den Remotezugriff
• Sicherheit — vollständiger Sicherheitsleitfaden
• Tailscale — einfachere Alternative für den Zugriff ausschließlich über das Tailnet