Autenticazione tramite proxy attendibile in OpenClaw

L’autenticazione tramite proxy attendibile è la modalità per i gateway che si trovano dietro un proxy consapevole dell’identità: il proxy autentica la persona, aggiunge un header con la sua identità e il gateway si fida di quell’header, ma solo se arriva dal proxy. La documentazione si apre con un avviso: una configurazione errata espone il gateway, e gran parte della pagina è l’elenco dei controlli che rendono sicura questa fiducia. Eccolo, nell’ordine in cui il gateway lo valuta.

Quando e come

• Usalo dietro Pomerium, Caddy con OAuth, nginx con oauth2-proxy o la forward auth di Traefik, in ambienti a container in cui il proxy è l’unico percorso, oppure quando i browser incontrano errori di autorizzazione WebSocket perché non possono passare token nell’handshake; non usarlo quando il proxy si limita a terminare il TLS, quando un qualsiasi percorso aggira il proxy, quando non sei sicuro che il proxy rimuova gli header inoltrati, o per un accesso personale a utente singolo, dove una tailnet più il loopback è più semplice.
• Il flusso: il proxy autentica l’utente, aggiunge un header di identità come l’header forwarded-user, il gateway verifica che la richiesta provenga da un indirizzo di proxy attendibile, legge gli header richiesti e l’identità dell’utente, e autorizza quando l’allowlist degli utenti, se impostata, include l’utente; la configurazione imposta il bind sulla rete locale, elenca solo gli indirizzi o gli intervalli del proxy, imposta la modalità di autenticazione, l’header utente, eventuali header richiesti, un’eventuale allowlist degli utenti, il loopback disattivato per impostazione predefinita e l’approvazione automatica dei dispositivi disattivata per impostazione predefinita.
• Regole di esecuzione in ordine: il traffico che si presenta come proveniente da un proxy viene attribuito prima dell’autenticazione del gateway e deve arrivare da un proxy attendibile con header dell’indirizzo client che risolvono verso un client non loopback, altrimenti le route autenticate dal gateway lo rifiutano per mancata attribuzione del proxy; il proxy deve sovrascrivere in modo sicuro la catena forwarded-for, e l’header dell’indirizzo reale viene accettato solo quando il relativo fallback è attivato; le sorgenti loopback vengono rifiutate a meno che l’opzione non sia true e il loopback non sia elencato anche come proxy attendibile; le sorgenti che corrispondono a uno degli indirizzi delle interfacce dell’host stesso vengono rifiutate come protezione contro lo spoofing, e anche una scoperta delle interfacce non riuscita porta al rifiuto; poi gli header richiesti e l’header utente devono essere presenti e non vuoti, e l’allowlist degli utenti deve includere l’utente.
• La presenza di header inoltrati su una richiesta loopback la esclude dal fallback con password locale diretta e dal controllo basato sull’identità del dispositivo, pur continuando a far fallire l’autenticazione trusted-proxy; i client interni che non passano dal proxy usano la password del gateway, che il comando status seleziona automaticamente senza un override dell’URL; l’elenco dei proxy attendibili accetta gli intervalli di indirizzi in forma semplice o in forma mappata, e un prefisso mappato che copre tutto richiede comunque l’opzione loopback per il loopback.

Un token del Gateway non può sostituire l’autenticazione tramite proxy.

Concessioni, approvazione automatica e header degli scope

Gli scope per identità danno a utenti verificati selezionati scope validi solo per la sessione, senza ampliare la concessione del loro dispositivo: la chiave è l’identità del proxy o il login della tailnet, le email corrispondono senza distinzione tra maiuscole e minuscole, la concessione viene unita agli scope autorizzati del dispositivo e poi limitata da un header degli scope esplicito, e le connessioni tramite token, password o senza autenticazione non ne ricevono mai una. L’approvazione automatica dei dispositivi, disattivata per impostazione predefinita, usa l’identità del proxy come confine di approvazione per i nuovi dispositivi operatore, sia browser sia nativi, e per gli ampliamenti di scope con la stessa chiave: si qualificano solo le connessioni trusted-proxy con un’identità non vuota che ha superato l’allowlist, mentre le connessioni con ruolo node e gli avanzamenti di ruolo non si qualificano mai, gli scope richiesti vengono intersecati con l’elenco configurato (read, write, approvals e questions quando non è impostato, mai ampliato), l’header degli scope del proxy limita anche la concessione persistente, e inserire admin nell’elenco permette a ogni utente del proxy di ricevere un dispositivo con pieni poteri di amministrazione, cosa che l’audit di sicurezza segnala come critica e di cui il gateway avvisa all’avvio. Le sessioni dell’interfaccia di controllo senza dispositivo non possono autodichiarare i propri scope: il loro elenco viene svuotato e viene applicata la concessione per identità corrispondente; un errore di scope mancante dopo una connessione riuscita significa che devi ricaricare la pagina perché il browser abbini l’identità del suo dispositivo. L’header degli scope dichiara degli scope quando è presente, non ne dichiara nessuno quando è presente ma vuoto e ricade sull’insieme predefinito dell’operatore quando è assente, mentre le route dei plugin con autenticazione del gateway ricadono solo su write.

TLS, token misti e audit

• Termina il TLS una sola volta e imposta lì l’header strict transport: sul proxy per le installazioni esposte a internet, con il gateway in loopback dietro di esso, oppure sul gateway con TLS attivato e l’header strict transport security quando è lui stesso a servire HTTPS; parti con un max age breve, aumentalo solo quando sei sicuro, aggiungi il flag dei sottodomini solo quando ogni sottodominio è pronto, e lascialo perdere per lo sviluppo solo in loopback.
• All’avvio l’autenticazione trusted-proxy viene rifiutata quando è configurato anche un token condiviso, perché un token permetterebbe ai chiamanti sullo stesso host di autenticarsi per un percorso diverso dall’identità verificata dal proxy; rimuovi il token o cambia modalità, e ricorda che gli header di identità in loopback continuano a essere rifiutati in modalità fail-closed e che il fallback tramite token non è supportato di proposito.
• L’audit di sicurezza segnala la modalità come critica per scelta progettuale e controlla se manca l’elenco dei proxy attendibili, se manca l’header utente, se l’allowlist degli utenti è vuota, se l’opzione loopback è attivata e se l’approvazione automatica dei dispositivi è attivata; la checklist aggiunge che il proxy è l’unico percorso, che l’elenco dei proxy attendibili è minimo, che il proxy sovrascrive gli header inoltrati e ricostruisce la catena forwarded-for, che le origini consentite sono esplicite per un’interfaccia di controllo non loopback e che qualsiasi fallback con password locale resta privato dietro il firewall.

La guida agli scope operatore di OpenClaw spiega il modello di scope che queste concessioni alimentano e OpenClaw su Tailscale l’alternativa più semplice per un accesso limitato alla tailnet.

Leggere i codici di rifiuto

La sezione sulla risoluzione dei problemi spiega ogni rifiuto: una sorgente non attendibile significa che la richiesta non è arrivata da un indirizzo di proxy elencato, e l’indirizzo del proxy cambia quando i container si riavviano; una sorgente loopback indica un proxy sullo stesso host senza l’opzione attivata deliberatamente; una sorgente di interfaccia locale significa che un processo sull’host del gateway sta inviando direttamente header di identità o che il proxy condivide il namespace di rete dell’host; un utente mancante significa che l’header è assente o ha un nome errato; un utente non consentito significa che l’account è autenticato ma non è nell’allowlist, e la documentazione raccomanda di non rimuovere l’allowlist come soluzione di ripiego; un’origine non consentita significa che l’origine del browser non ha superato la verifica dell’interfaccia di controllo. Il messaggio secondo cui è richiesta l’autenticazione tramite proxy indica un’identità rifiutata, non un’interruzione di rete, e la soluzione è accedere tramite il proxy invece di inviare header dal browser. La migrazione dall’autenticazione tramite token richiede sei passaggi: configurare il proxy, testarlo in modo indipendente, aggiornare la configurazione del gateway, riavviare, testare il WebSocket dall’interfaccia di controllo ed eseguire l’audit. L’articolo sull’accesso remoto di OpenClaw confronta gli altri schemi di accesso remoto, mentre quello sull’abbinamento di OpenClaw descrive il flusso dei dispositivi che l’approvazione automatica sostituisce.

Su Diali

Su Diali ogni gateway dei clienti è raggiungibile tramite l’ingress della piattaforma, con la configurazione del motore generata dalla dashboard e sostituita a ogni rilascio, quindi questa modalità non è qualcosa che un cliente debba assemblare a mano. OpenClaw ospitato su Diali descrive l’assistente ospitato e la pagina sulla sicurezza di Diali il confine attorno a ogni motore.

• Fidati dell’header solo se arriva dagli indirizzi di proxy elencati.
• Le sorgenti loopback e quelle delle proprie interfacce vengono rifiutate in modalità fail-closed.
• L’header degli scope restringe; le concessioni per identità aggiungono, solo per la sessione.