Permessi Cloudflare Workers: circoscrivere il deploy per cliente

I permessi Cloudflare Workers basati su quattro ruoli trasformano un'unica credenziale di deploy condivisa in un confine per singolo cliente. Dal 15 settembre 2026, un'agenzia può consentire al job CI di un cliente di distribuire un solo Worker già esistente, senza concedergli anche il diritto di eliminarlo o l'accesso a tutti gli altri Worker dell'account, purché nessuna policy più ampia estenda quei permessi.

Il vero passo avanti dei permessi Cloudflare Workers è lo scope

Un'autorizzazione ha due componenti. Il ruolo stabilisce che cosa si può fare; lo scope definisce dove lo si può fare.

Cloudflare ora permette di associare un ruolo Worker allo scope di un singolo Worker per un collaboratore, un User Group, un agente o un token API. Lo stesso ruolo può ancora coprire tutti i Worker, ma non è più obbligatorio.

Può sembrare una piccola novità amministrativa. Per uno studio o un'agenzia che gestisce più clienti nello stesso account Cloudflare, cambia invece il passaggio di consegne: la credenziale di deploy del Cliente A può fermarsi al Worker del Cliente A.

Il rilascio del 15 settembre è disponibile per tutti i clienti e si gestisce dalla dashboard, tramite API o con Terraform.

Ecco l'intero set di ruoli indicato nella documentazione dei ruoli Workers:

Questa separazione è utile perché diagnosticare un problema, revisionare il codice, pubblicarlo ed eliminare il servizio sono quattro attività diverse. Non dovrebbero ereditare tutte la stessa credenziale.

I precedenti permessi Workers di Cloudflare operavano a livello di account. Il nuovo modello può essere applicato all'intera Developer Platform, a tutti i Worker oppure a un singolo Worker esistente. Una policy Workers a livello di prodotto include tutti i Worker presenti e futuri; una policy per singolo Worker copre soltanto quelli selezionati.

Resta un limite strutturale: non si può assegnare uno scope a un Worker che ancora non esiste. Per crearne uno nuovo serve ancora Admin a livello di prodotto.

Cosa cambia nel passaggio di consegne a un cliente

Immaginiamo una piccola agenzia che ospita un Worker per ogni cliente. Il suo flusso di deploy deve pubblicare nuove versioni di client-a-api; non deve creare Worker, eliminare quel Worker né intervenire su client-b-checkout.

Prima di questo rilascio, i comuni permessi CI per Workers che Cloudflare ora definisce legacy erano a livello di account. Le alternative sensate erano due: accettare una credenziale molto ampia oppure spostare il cliente in un altro account. Lo scope per singolo Worker ne aggiunge una terza: mantenere invariata la struttura dell'account e assegnare al token di deploy il ruolo Editor soltanto su client-a-api.

I conti sull'abbonamento non cambiano, perché i controlli a livello di Worker sono disponibili per tutti i clienti. Cambiano quelli operativi.

Il modello tralascia un compromesso importante. Dodici credenziali con scope per cliente comportano più segreti da emettere, conservare e ruotare rispetto a un unico token condiviso. Il vantaggio non consiste nell'avere meno credenziali, ma nel ridurre il numero di progetti da esaminare quando una credenziale smette di funzionare o viene compromessa.

Un founder che lavora da solo, con un unico Worker e nessun accesso di deploy condiviso, noterà ben poco. Lo stesso vale per un team che sceglie consapevolmente di affidare al gruppo di piattaforma il controllo di tutti i Worker. La novità conta quando più persone, clienti o processi automatizzati condividono un account Cloudflare, ma non dovrebbero condividere lo stesso raggio d'impatto.

Assegnare a un job di deploy cliente solo i permessi necessari

Il passaggio di consegne più lineare parte da un Worker esistente con Route o Custom Domain stabili. In questo modo, la creazione del Worker e le modifiche al dominio restano fuori dal job di deploy.

1. 1

   Definire il compito prima di scegliere il ruolo

   Si parte da una frase: “Questo workflow distribuisce nuove versioni del Worker client-a-api esistente”.

   La frase porta a Editor con scope sul singolo Worker. Se il job deve creare un nuovo Worker, occorre Admin a livello di prodotto. Se deve aggiungere, modificare o rimuovere una Route o un Custom Domain, serve anche Workers Routes Write per ogni zona interessata.

2. 2

   Creare un token API di proprietà dell'account

   In Cloudflare, aprire Manage Account > Account API Tokens e creare un token di proprietà dell'account. Impostare lo scope su Specified Workers, selezionare client-a-api, quindi scegliere Editor.

   Per il workflow va usato un token di proprietà dell'account, non il token personale di un utente. Cloudflare presenta questi token come service principal per integrazioni durature: il deploy non si interrompe quando lascia l'azienda la persona che lo ha creato. Per crearne o aggiornarne uno è necessario il permesso Super Administrator.

3. 3

   Eseguire Wrangler con quel token

   Salvare il token nell'archivio dei segreti del sistema di deploy. Cloudflare documenta queste variabili d'ambiente per Wrangler:

   export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
   export CLOUDFLARE_ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
   npx wrangler deploy

   Il comando va eseguito dal progetto configurato per il Worker esistente. wrangler login non è un'alternativa in questo caso, perché il suo flusso OAuth al momento non supporta l'autorizzazione granulare.

4. 4

   Passare al nuovo token e rimuovere l'accesso più ampio

   Distribuire una versione innocua con il nuovo token e verificare che venga aggiornato il Worker previsto. Controllare che il token non abbia alcun ruolo Workers a livello di prodotto né scope su risorse non correlate.

   Poi rimuovere dal workflow il vecchio segreto di deploy con permessi estesi. Mantenere entrambe le credenziali durante il test è ragionevole; conservarle entrambe dopo il test annulla il confine appena creato.

Questo è l'intero passaggio di consegne per un deploy ordinario. Il job del cliente può aggiornare, caricare, distribuire, ripristinare, rinominare e gestire i segreti di quel Worker, perché sono tutte operazioni comprese in Editor. Non può eliminare il Worker e la policy per singolo Worker non gli concede accesso agli altri Worker.

Quattro attività, quattro policy sensate

Un agente di supporto che deve soltanto raccogliere evidenze

Assegnare a un agente di debug Metadata Read-Only sul Worker interessato. Potrà esaminare impostazioni, metriche, log e tracce senza leggere il codice sorgente né modificare il servizio.

Il risultato è un workflow di supporto capace di raccogliere evidenze senza trasformarsi silenziosamente in un flusso di revisione del codice o di deploy. Lo stesso ruolo basta per wrangler tail su quel Worker.

Uno sviluppatore esterno che revisiona il progetto di un cliente

Assegnare al collaboratore Content Read-Only sul Worker del cliente. Potrà consultare il codice distribuito e le impostazioni, ma non modificarlo né eseguirne il deploy.

Il confine della revisione diventa più netto. Non serve concedere Editor solo perché chi effettua la verifica deve capire che cosa è in esecuzione.

Una pipeline CI dedicata a un cliente

Assegnare al token di proprietà dell'account il ruolo Editor su un solo Worker esistente. Potrà pubblicare versioni e ripristinarle senza eliminare il Worker né raggiungere quelli degli altri clienti.

È la soluzione più adatta al passaggio di consegne di un'agenzia, perché la credenziale appartiene al workflow e non a un membro del personale. Se per i progetti dei clienti vengono usati anche agenti browser, i controlli sugli host approvati di Cloudflare risolvono un'altra metà del confine: dove può navigare il browser. Questo rilascio stabilisce invece quale Worker può modificare l'identità di deploy.

Un responsabile di piattaforma che gestisce il ciclo di vita

Riservare Admin al collaboratore o all'automazione che ha davvero bisogno di eliminare Worker. Admin a livello di prodotto deve restare al responsabile che crea i Worker; una volta completato il Worker, la gestione quotidiana può passare a policy più ristrette.

Il vantaggio è una separazione evidente tra le attività legate al ciclo di vita e la distribuzione ordinaria. Un job di deploy non ha bisogno della stessa autorità di chi crea e dismette i servizi dei clienti.

Il confine si restringe, ma non equivale a un isolamento completo

Il vantaggio principale è concreto, ma ridurre tutto a “un solo Worker” può essere pericoloso.

I Durable Objects richiedono la stessa attenzione. Non dispongono di ruoli o scope indipendenti: ereditano l'accesso dal Worker che li implementa. Metadata Read-Only include metriche, log e tracce dei Durable Objects senza accesso ai dati archiviati, mentre Editor raggiunge anche il livello di autorizzazione documentato per usare Data Studio e interrogare o modificare i dati di un Durable Object basato su SQLite.

Le Route costituiscono un altro confine separato. Editor è sufficiente per distribuire una nuova versione quando una Route o un Custom Domain esistenti restano invariati. Per modificare quel collegamento serve anche Workers Routes Write per ogni zona coinvolta. Cloudflare precisa inoltre che i Custom Domain al momento non supportano i ruoli per singolo Worker.

Infine, i permessi Cloudflare sono cumulativi. Una policy diretta e restrittiva non annulla una policy più ampia ereditata tramite un User Group. La vista Members mostra i permessi diretti, mentre le policy ereditate dai gruppi vanno controllate nella scheda Groups. Se si salta questa verifica, lo schermo può mostrare la policy ristretta desiderata anche se il set di permessi effettivi rimane ampio.

Chi dovrebbe intervenire adesso

Conviene agire questa settimana se un account contiene più Worker di clienti e una persona, un agente o un job CI conserva ancora un permesso su tutti i Worker per svolgere un'attività limitata a uno solo. Il beneficio è più evidente quando il Worker esiste già e i collegamenti al dominio non cambiano durante i deploy ordinari.

Prima di restringere il token, è meglio attendere se il workflow crea Worker, modifica Route o Custom Domain oppure dipende dall'accesso diretto ai prodotti dati collegati. Queste operazioni vanno mappate in anticipo, altrimenti il deploy successivo si interromperà a metà.

La novità non ha effetti su chi non condivide mai l'accesso ai Worker, gestisce un solo Worker oppure affida intenzionalmente il deploy a un team di piattaforma con responsabilità estese all'intero account.

La mossa da fare lunedì

Iniziare dalla policy dei permessi dietro il deploy CI di un cliente esistente. Impostare un token di proprietà dell'account su Editor, limitarne lo scope a quel solo Worker, elencare ogni binding e ogni Durable Object ereditato su cui può intervenire, controllare le policy dirette e di gruppo, quindi eseguire il deploy senza modificare la Route o il Custom Domain.

Una volta superata la prova, rimuovere il vecchio segreto con accesso a tutti i Worker. Questo singolo passaggio crea un confine reale e un modello replicabile per il cliente successivo.

Per ricevere altre note operative sulle novità delle piattaforme, spiegate con chiarezza, è possibile iscriversi alla newsletter.