Authentification par proxy de confiance

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Quand l’utiliser

• 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

• 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: ["nick@example.com", "admin@company.org"],

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

​

Référence de configuration

​

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 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: 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",
      },
    },
  },
}

​

Configuration mixte de jeton

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

​

En-tête des portées 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 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.

​

Liste de contrôle de sécurité

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

• 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

​

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