Autenticazione tramite proxy attendibile

​

Quando utilizzarla

• Esegui OpenClaw dietro un proxy con riconoscimento dell’identità (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + autenticazione inoltrata).
• Il proxy gestisce tutta l’autenticazione e trasmette l’identità dell’utente tramite intestazioni.
• Ti trovi in un ambiente Kubernetes o containerizzato in cui il proxy è l’unico percorso verso il Gateway.
• Riscontri errori WebSocket 1008 unauthorized perché i browser non possono trasmettere token nei payload WS.

​

Quando NON utilizzarla

• Il proxy non autentica gli utenti, ma funge soltanto da terminatore TLS o bilanciatore del carico.
• Esiste un qualsiasi percorso verso il Gateway che aggira il proxy, ad esempio aperture nel firewall o accesso dalla rete interna.
• Non hai la certezza che il proxy rimuova o sovrascriva correttamente le intestazioni inoltrate.
• Ti serve soltanto un accesso personale per un singolo utente; valuta invece Tailscale Serve + local loopback.

​

Come funziona

​

Configurazione

{
  gateway: {
    // Trusted-proxy auth expects the proxy's source IP to be non-loopback 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,
      },
    },
  },
}

​

Riferimento della configurazione

​

Comportamento di associazione della Control UI

• Le sessioni WebSocket della Control UI prive di dispositivo si connettono, ma per impostazione predefinita non ricevono alcun ambito operatore. OpenClaw azzera a [] l’elenco degli ambiti richiesti, affinché una sessione non associata a un dispositivo/token approvato non possa dichiarare autonomamente le proprie autorizzazioni.
• Se i metodi restituiscono missing scope dopo una connessione WebSocket riuscita, utilizza HTTPS affinché il browser possa generare l’identità del dispositivo e completare l’associazione. Consulta HTTP non sicuro della Control UI.
• Solo in caso di emergenza: gateway.controlUi.dangerouslyDisableDeviceAuth=true conserva gli ambiti richiesti anche senza identità del dispositivo. Ciò riduce gravemente la sicurezza; ripristina rapidamente l’impostazione precedente. Consulta HTTP non sicuro della Control UI.

• In questa modalità, l’associazione non è più il controllo principale per l’accesso alla Control UI.
• I criteri di autenticazione del proxy inverso e allowUsers diventano il controllo degli accessi effettivo.
• Limita l’ingresso al Gateway esclusivamente agli IP dei proxy attendibili (gateway.trustedProxies + firewall).

​

Intestazione degli ambiti operatore

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

• Quando l’intestazione è presente, OpenClaw rispetta l’insieme di ambiti dichiarato.
• Quando l’intestazione è presente ma vuota, la richiesta dichiara di non avere alcun ambito operatore.
• Quando l’intestazione è assente, le normali API HTTP che includono l’identità utilizzano come fallback l’insieme standard predefinito degli ambiti operatore (operator.admin, operator.read, operator.write, operator.approvals, operator.pairing, operator.talk.secrets).
• Per impostazione predefinita, le route HTTP dei Plugin con autenticazione Gateway sono più restrittive: quando x-openclaw-scopes è assente, il relativo ambito di runtime utilizza come fallback soltanto operator.write.
• Le richieste HTTP provenienti dal browser devono comunque superare il controllo gateway.controlUi.allowedOrigins, o la modalità di fallback deliberata basata sull’intestazione Host, anche dopo il successo dell’autenticazione tramite proxy attendibile.

​

Terminazione TLS e HSTS

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

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

​

Indicazioni per l’implementazione

• Inizia con una durata massima breve, ad esempio max-age=300, durante la convalida del traffico.
• Passa a valori di lunga durata, ad esempio max-age=31536000, soltanto dopo aver raggiunto un elevato grado di affidabilità.
• Aggiungi includeSubDomains soltanto se ogni sottodominio è predisposto per HTTPS.
• Utilizza il precaricamento soltanto se soddisfi intenzionalmente i relativi requisiti per l’intero insieme dei domini.
• Lo sviluppo locale limitato a local loopback non trae vantaggio da HSTS.

​

Esempi di configurazione del 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",
      },
    },
  },
}

​

Configurazione mista dei token

• Rimuovi il token condiviso quando utilizzi la modalità proxy attendibile, oppure
• Imposta gateway.auth.mode su "token" se intendi utilizzare l’autenticazione basata su token.

​

Elenco di controllo della sicurezza

• Il proxy è l’unico percorso: la porta del Gateway è protetta da firewall e accessibile esclusivamente dal proxy.
• trustedProxies è ridotto al minimo: include solo gli indirizzi IP effettivi del proxy, non intere sottoreti.
• L’origine local loopback del proxy è intenzionale: l’autenticazione tramite proxy attendibile rifiuta l’accesso in caso di errore per le richieste provenienti dal local loopback, a meno che gateway.auth.trustedProxy.allowLoopback non sia esplicitamente abilitato per un proxy sullo stesso host.
• Il proxy elimina le intestazioni: il proxy sovrascrive, senza aggiungere valori, le intestazioni x-forwarded-* provenienti dai client.
• Terminazione TLS: il proxy gestisce TLS; gli utenti si connettono tramite HTTPS.
• allowedOrigins è esplicito: l’interfaccia di controllo non in local loopback utilizza un valore esplicito per gateway.controlUi.allowedOrigins.
• allowUsers è impostato (consigliato): limita l’accesso agli utenti noti anziché consentirlo a chiunque sia autenticato.
• Nessuna configurazione mista dei token: non impostare contemporaneamente gateway.auth.token e gateway.auth.mode: "trusted-proxy".
• Il ripiego sulla password locale è privato: se configuri gateway.auth.password per i chiamanti interni diretti, proteggi la porta del Gateway con un firewall affinché i client remoti che non passano dal proxy non possano raggiungerla direttamente.

​

Controllo di sicurezza

• Avviso o promemoria critico di base gateway.trusted_proxy_auth.
• Configurazione trustedProxies mancante.
• Configurazione userHeader mancante.
• allowUsers vuoto, che consente l’accesso a qualsiasi utente autenticato.
• allowLoopback abilitato per le origini proxy sullo stesso host.

​

Risoluzione dei problemi

​

Migrazione dall’autenticazione tramite token

​

Argomenti correlati

• Configurazione — riferimento della configurazione
• Ambiti dell’operatore — ruoli, ambiti e controlli di approvazione
• Accesso remoto — altri modelli di accesso remoto
• Sicurezza — guida completa alla sicurezza
• Tailscale — alternativa più semplice per l’accesso limitato alla tailnet