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

Lorsque gateway.auth.mode = "trusted-proxy" est actif et que la requête réussit les vérifications du proxy approuvé, les sessions WebSocket de l’interface de contrôle peuvent se connecter sans identité d’association d’appareil.

Conséquences sur les portées :

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

Limitation des portées par le proxy inverse : si votre proxy envoie x-openclaw-scopes dans la requête de mise à niveau WebSocket de l’interface de contrôle, OpenClaw limite les portées de la session à l’intersection des portées demandées et des portées déclarées. Cet en-tête n’accorde aucune portée ; il réduit uniquement celles que la session peut détenir.

Conséquences :

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

Les clients WebSocket personnalisés ne sont pas des sessions de l’interface de contrôle. gateway.controlUi.dangerouslyDisableDeviceAuth n’accorde aucune portée aux clients arbitraires ayant la forme client.mode: "backend" ou CLI. Les automatisations personnalisées doivent utiliser l’identité et l’association d’appareil, le chemin d’assistance backend local direct réservé client.id: "gateway-client" ou le Plugin RPC HTTP d’administration lorsqu’une interface de requête-réponse HTTP convient mieux.

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

L’authentification par proxy approuvé est un mode HTTP porteur d’identité ; les appelants peuvent donc éventuellement déclarer des portées d’opérateur avec x-openclaw-scopes dans les requêtes d’API HTTP.

Remarque : les portées WebSocket sont déterminées par l’établissement de liaison du protocole Gateway et la liaison à l’identité de l’appareil. Dans les requêtes de mise à niveau WebSocket de l’interface de contrôle, x-openclaw-scopes ne fait que limiter les portées négociées de la session ; il ne les accorde pas. Consultez Comportement d’association de l’interface de contrôle.

Exemples :

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

Comportement :

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

Règle pratique : envoyez explicitement x-openclaw-scopes lorsque vous souhaitez qu’une requête par proxy approuvé soit plus restrictive que les valeurs par défaut, ou lorsqu’une route de Plugin authentifiée par le Gateway nécessite une portée supérieure à celle d’écriture.

Terminaison TLS et HSTS

Utilisez un seul point de terminaison TLS et appliquez-y 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

Le démarrage du Gateway refuse l'authentification par proxy de confiance si un jeton partagé est également configuré (gateway.auth.token ou OPENCLAW_GATEWAY_TOKEN). Ces deux méthodes s'excluent mutuellement, car un jeton partagé permettrait aux appelants du même hôte de s'authentifier par une voie totalement différente de l'identité vérifiée par le proxy que ce mode est censé imposer.

Si le démarrage échoue avec une erreur telle que gateway auth mode is trusted-proxy, but a shared token is also configured :

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

Les en-têtes d'identité du proxy de confiance provenant de l'interface de bouclage continuent d'être refusés par défaut : les appelants du même hôte ne sont pas silencieusement authentifiés comme utilisateurs du proxy. Les appelants internes d'OpenClaw qui contournent le proxy peuvent s'authentifier avec gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD à la place. Le recours de secours à un jeton reste intentionnellement non pris en charge en mode proxy de confiance.

Liste de contrôle de sécurité

Avant d'activer l'authentification par proxy de confiance, vérifiez les points suivants :

• [ ] 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é

openclaw security audit signale l'authentification par proxy de confiance avec un constat de gravité critique. Ce comportement est intentionnel ; il rappelle que vous déléguez la sécurité à la configuration de votre proxy.

L'audit vérifie les éléments suivants :

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

Des constats distincts, qui ne sont pas propres au proxy de confiance, s'appliquent également chaque fois que l'interface de contrôle est exposée : valeur générique ou absence de gateway.controlUi.allowedOrigins, ainsi que recours à l'origine fondée sur l'en-tête Host.

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