Authentification par proxy de confiance

​

Quand l’utiliser

• Vous exécutez OpenClaw derrière un proxy tenant compte de l’identité (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + authentification transférée).
• Votre proxy gère toute l’authentification et transmet l’identité de l’utilisateur au moyen d’en-têtes.
• Vous utilisez un environnement Kubernetes ou de conteneurs dans lequel le proxy constitue le seul chemin vers le Gateway.
• Vous rencontrez des erreurs WebSocket 1008 unauthorized, car les navigateurs ne peuvent pas transmettre de jetons dans les charges utiles WS.

​

Quand NE PAS l’utiliser

• Votre proxy n’authentifie pas les utilisateurs (il sert uniquement de terminaison TLS ou d’équilibreur de charge).
• Il existe un chemin vers le Gateway qui contourne le proxy (ouvertures dans le pare-feu, accès au réseau interne).
• Vous ne savez pas si votre proxy supprime ou remplace correctement les en-têtes transférés.
• Vous avez uniquement besoin d’un accès personnel pour un seul utilisateur (envisagez plutôt Tailscale Serve + local loopback).

​

Fonctionnement

​

Configuration

{
  gateway: {
    // L’authentification par proxy approuvé exige par défaut que l’adresse IP source du proxy ne soit pas une adresse de bouclage
    bind: "lan",

    // CRITIQUE : ajoutez uniquement ici les adresses IP de votre proxy
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // En-tête contenant l’identité de l’utilisateur authentifié (obligatoire)
        userHeader: "x-forwarded-user",

        // Facultatif : en-têtes qui DOIVENT être présents (vérification du proxy)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Facultatif : limiter l’accès à certains utilisateurs (vide = tous les autoriser)
        allowUsers: ["nick@example.com", "admin@company.org"],

        // Facultatif : autoriser un proxy local loopback sur le même hôte après une activation explicite
        allowLoopback: false,
      },
    },
  },
}

​

Référence de configuration

​

Comportement d’association de l’interface de contrôle

• Les sessions WebSocket de l’interface de contrôle sans appareil se connectent, mais ne reçoivent par défaut aucune portée d’opérateur. OpenClaw vide la liste des portées demandées en la définissant sur [], afin qu’une session non liée à un appareil ou jeton associé et approuvé ne puisse pas déclarer elle-même des autorisations.
• Si des méthodes échouent avec missing scope après une connexion WebSocket réussie, utilisez HTTPS afin que le navigateur puisse générer une identité d’appareil et terminer l’association. Consultez HTTP non sécurisé de l’interface de contrôle.
• Uniquement en cas d’urgence : gateway.controlUi.dangerouslyDisableDeviceAuth=true conserve les portées demandées même sans identité d’appareil. Cela réduit fortement la sécurité ; annulez rapidement ce réglage. Consultez HTTP non sécurisé de l’interface de contrôle.

• L’association n’est plus le principal mécanisme de contrôle de l’accès à l’interface de contrôle dans ce mode.
• La politique d’authentification de votre proxy inverse et allowUsers deviennent le contrôle d’accès effectif.
• Limitez strictement l’entrée du Gateway aux seules adresses IP de proxy approuvées (gateway.trustedProxies + pare-feu).

​

En-tête des portées d’opérateur

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

• Lorsque l’en-tête est présent, OpenClaw respecte l’ensemble des portées déclarées.
• Lorsque l’en-tête est présent, mais vide, la requête ne déclare aucune portée d’opérateur.
• Lorsque l’en-tête est absent, les API HTTP ordinaires porteuses d’identité utilisent par repli l’ensemble standard de portées d’opérateur par défaut (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Les routes HTTP de Plugin authentifiées par le Gateway sont plus restrictives par défaut : lorsque x-openclaw-scopes est absent, leur portée d’exécution se limite par repli à operator.write.
• Les requêtes HTTP provenant d’un navigateur doivent toujours respecter gateway.controlUi.allowedOrigins (ou le mode de repli délibéré basé sur l’en-tête Host), même après la réussite de l’authentification par proxy approuvé.

​

Terminaison TLS et HSTS

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

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

​

Conseils de déploiement

• Commencez par une durée maximale courte (par exemple max-age=300) pendant la validation du trafic.
• Passez à des valeurs de longue durée (par exemple max-age=31536000) uniquement lorsque votre niveau de confiance est élevé.
• Ajoutez includeSubDomains uniquement si chaque sous-domaine est prêt pour HTTPS.
• Utilisez le préchargement uniquement si vous respectez volontairement ses exigences pour l’ensemble de vos domaines.
• Le développement local limité à local loopback ne bénéficie pas de HSTS.

​

Exemples de configuration de proxy

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Adresse IP de 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"], // Adresse IP du proxy Caddy/sidecar
    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"], // Adresse IP de 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"], // Adresse IP du conteneur Traefik
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

Configuration mixte avec jeton

• Supprimez le jeton partagé lorsque vous utilisez le mode proxy de confiance, ou
• Définissez gateway.auth.mode sur "token" si vous souhaitez une authentification par jeton.

​

Liste de contrôle de sécurité

• Le proxy est le seul chemin d’accès : le port du Gateway est protégé par un pare-feu contre tout accès autre que celui de votre proxy.
• trustedProxies est minimal : uniquement les adresses IP réelles de vos proxys, et non des sous-réseaux entiers.
• La source du proxy sur l’interface de bouclage est intentionnelle : l’authentification par proxy de confiance refuse par défaut les requêtes provenant de l’interface de bouclage, sauf si gateway.auth.trustedProxy.allowLoopback est explicitement activé pour un proxy situé sur le même hôte.
• Le proxy supprime les en-têtes : votre proxy remplace, sans les compléter, les en-têtes x-forwarded-* provenant des clients.
• Terminaison TLS : votre proxy gère TLS ; les utilisateurs se connectent via HTTPS.
• allowedOrigins est explicite : l’interface de contrôle utilisée hors de l’interface de bouclage emploie une valeur explicite pour gateway.controlUi.allowedOrigins.
• allowUsers est défini (recommandé) : limitez l’accès aux utilisateurs connus plutôt que de l’autoriser à toute personne authentifiée.
• Aucune configuration mixte avec jeton : ne définissez pas simultanément gateway.auth.token et gateway.auth.mode: "trusted-proxy".
• Le mot de passe local de secours reste privé : si vous configurez gateway.auth.password pour des appelants internes directs, protégez le port du Gateway par un pare-feu afin que les clients distants ne passant pas par le proxy ne puissent pas y accéder directement.

​

Audit de sécurité

• Avertissement ou rappel critique de base gateway.trusted_proxy_auth.
• Configuration trustedProxies manquante.
• Configuration userHeader manquante.
• allowUsers vide, ce qui autorise tout utilisateur authentifié.
• allowLoopback activé pour les sources de proxy situées sur le même hôte.

​

Résolution des problèmes

​

Migration depuis l’authentification par jeton

​

Pages connexes

• Configuration — référence de configuration
• Portées de l’opérateur — rôles, portées et contrôles d’approbation
• Accès distant — autres modèles d’accès distant
• Sécurité — guide de sécurité complet
• Tailscale — solution plus simple pour un accès limité au réseau privé Tailscale