Authentification par proxy de confiance

# Quand l’utiliser

Utilisez le mode d’authentification trusted-proxy lorsque :

• Vous exécutez OpenClaw derrière un proxy sensible à l’identité (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Votre proxy gère toute l’authentification et transmet l’identité de l’utilisateur via des en-têtes.
• Vous êtes dans un environnement Kubernetes ou conteneurisé où le proxy est le seul chemin vers la Gateway.
• Vous rencontrez des erreurs WebSocket 1008 unauthorized parce que les navigateurs ne peuvent pas transmettre de jetons dans les charges utiles WS.

# Quand NE PAS l’utiliser

• Si votre proxy n’authentifie pas les utilisateurs (simple terminaison TLS ou équilibreur de charge).
• S’il existe un chemin vers la Gateway qui contourne le proxy (ouvertures de pare-feu, accès au réseau interne).
• Si vous n’êtes pas sûr que votre proxy supprime/remplace correctement les en-têtes transférés.
• Si vous avez seulement besoin d’un accès personnel mono-utilisateur (envisagez Tailscale Serve + loopback pour une configuration plus simple).

# Fonctionnement

# Comportement d’appairage de Control UI

Lorsque gateway.auth.mode = "trusted-proxy" est actif et que la requête passe les vérifications trusted-proxy, les sessions WebSocket Control UI peuvent se connecter sans identité d’appairage d’appareil.

Conséquences :

• L’appairage n’est plus la barrière principale pour l’accès à Control UI dans ce mode.
• La politique d’authentification de votre proxy inverse et allowUsers deviennent le contrôle d’accès effectif.
• Gardez l’entrée de la Gateway limitée aux seules IP de proxy de confiance (gateway.trustedProxies + pare-feu).

# Configuration

{
  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: ["[email protected]", "[email protected]"],

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

# Référence de configuration

# 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 un âge maximal court (par exemple max-age=300) pendant la validation du trafic.
• Passez à des valeurs de longue durée (par exemple max-age=31536000) uniquement lorsque la confiance est élevée.
• Ajoutez includeSubDomains uniquement si chaque sous-domaine est prêt pour HTTPS.
• Utilisez preload uniquement si vous respectez intentionnellement les exigences de preload pour l’ensemble de vos domaines.
• Le développement local limité à loopback ne bénéficie pas de HSTS.

# Exemples de configuration de proxy

{
  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: [email protected]
    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",
      },
    },
  },
}

# Configuration mixte de jeton

OpenClaw rejette les configurations ambiguës où un gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN) et le mode trusted-proxy sont actifs en même temps. Les configurations mixtes de jeton peuvent amener les requêtes loopback à s’authentifier silencieusement via le mauvais chemin d’authentification.

Si vous voyez une erreur mixed_trusted_proxy_token au démarrage :

• Supprimez le jeton partagé lorsque vous utilisez le mode trusted-proxy, ou
• Basculez gateway.auth.mode vers "token" si vous souhaitez une authentification basée sur un jeton.

Les en-têtes d’identité trusted-proxy en loopback échouent toujours de façon fermée : les appelants sur le même hôte ne sont pas authentifiés silencieusement comme utilisateurs de proxy. Les appelants internes d’OpenClaw qui contournent le proxy peuvent plutôt s’authentifier avec gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Le repli par jeton reste intentionnellement non pris en charge en mode trusted-proxy.

# En-tête des portées opérateur

L’authentification trusted-proxy est un mode HTTP porteur d’identité ; les appelants peuvent donc déclarer facultativement des portées opérateur avec x-openclaw-scopes.

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 de portées déclaré.
• Lorsque l’en-tête est présent mais vide, la requête ne déclare aucune portée opérateur.
• Lorsque l’en-tête est absent, les API HTTP porteuses d’identité normales reviennent à l’ensemble de portées opérateur par défaut standard.
• Les routes HTTP de Plugin avec authentification Gateway sont plus restreintes par défaut : lorsque x-openclaw-scopes est absent, leur portée d’exécution revient à operator.write.
• Les requêtes HTTP provenant d’un navigateur doivent toujours passer gateway.controlUi.allowedOrigins (ou le mode de repli volontaire par en-tête Host), même après la réussite de l’authentification trusted-proxy.

Règle pratique : envoyez x-openclaw-scopes explicitement lorsque vous voulez qu’une requête trusted-proxy soit plus restreinte que les valeurs par défaut, ou lorsqu’une route de Plugin avec authentification Gateway nécessite une portée plus forte que l’écriture.

# Liste de contrôle de sécurité

Avant d’activer l’authentification trusted-proxy, vérifiez :

• [ ] Le proxy est le seul chemin : le port du Gateway est protégé par pare-feu contre tout accès, sauf depuis votre proxy.
• [ ] trustedProxies est minimal : uniquement les adresses IP réelles de votre proxy, pas des sous-réseaux entiers.
• [ ] La source du proxy en bouclage est délibérée : l’authentification trusted-proxy échoue fermée pour les requêtes provenant d’une source en bouclage, sauf si gateway.auth.trustedProxy.allowLoopback est explicitement activé pour un proxy sur le même hôte.
• [ ] Le proxy supprime les en-têtes : votre proxy remplace (n’ajoute pas) 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 : une Control UI hors bouclage utilise gateway.controlUi.allowedOrigins explicite.
• [ ] allowUsers est défini (recommandé) : limitez l’accès aux utilisateurs connus plutôt que d’autoriser toute personne authentifiée.
• [ ] Aucune configuration de jeton mixte : ne définissez pas à la fois gateway.auth.token et gateway.auth.mode: "trusted-proxy".
• [ ] Le repli par mot de passe local est privé : si vous configurez gateway.auth.password pour les appelants directs internes, gardez le port du Gateway protégé par pare-feu afin que les clients distants hors proxy ne puissent pas l’atteindre directement.

# Audit de sécurité

openclaw security audit signalera l’authentification trusted-proxy avec une conclusion de gravité critique. C’est intentionnel : c’est un rappel que vous déléguez la sécurité à votre configuration de proxy.

L’audit vérifie :

• Rappel d’avertissement/critique de base gateway.trusted_proxy_auth
• Configuration trustedProxies manquante
• Configuration userHeader manquante
• allowUsers vide (autorise tout utilisateur authentifié)
• allowLoopback activé pour les sources de proxy sur le même hôte
• Politique d’origine du navigateur avec joker ou manquante sur les surfaces Control UI exposées

# Dépannage

# Migration depuis l’authentification par jeton

Si vous passez de l’authentification par jeton à trusted-proxy :

# Connexe

• Configuration — référence de configuration
• 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 tailnet