Scopri la sintassi principale del linguaggio Regole di sicurezza Firebase per Cloud Storage

Firebase Security Rules per Cloud Storage ti consente di controllare l'accesso agli oggetti archiviati negli archivio di oggetti Cloud Storage. La sintassi flessibile delle regole ti consente di creare regole per controllare qualsiasi operazione, da tutte le scritture nel tuo bucket Cloud Storage alle operazioni su un file specifico.

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Cloud Storage data.

Questa guida descrive la sintassi e la struttura di base di Cloud Storage Security Rules per creare set di regole completi.

Dichiarazione su servizi e database

Firebase Security Rules per Cloud Storage inizia sempre con la seguente dichiarazione:

service firebase.storage {
    // ...
}

La dichiarazione service firebase.storage limita l'ambito delle regole a Cloud Storage, evitando conflitti tra Cloud Storage Security Rules e le regole per altri prodotti come Cloud Firestore.

Regole di lettura/scrittura di base

Le regole di base sono costituite da un'istruzione match che identifica i bucket Cloud Storage, un'istruzione di corrispondenza che specifica un nome file e un'espressione allow che indica quando è consentita la lettura dei dati specificati. Le espressioni allow specificano i metodi di accesso (ad esempio lettura, scrittura) coinvolti e le condizioni in base alle quali l'accesso è consentito o negato.

Nel set di regole predefinito, la prima istruzione match utilizza un'espressione con caratteri jolly {bucket} per indicare che le regole si applicano a tutti i bucket del progetto. Parleremo più approfonditamente dell'idea delle corrispondenze con caratteri jolly nella prossima sezione.

service firebase.storage {
  // The {bucket} wildcard indicates we match files in all Cloud Storage buckets
  match /b/{bucket}/o {
    // Match filename
    match /filename {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

Tutte le istruzioni match puntano ai file. Un'istruzione match può puntare a un file specifico, come in match /images/profilePhoto.png.

Caratteri jolly di corrispondenza

Oltre a puntare a un singolo file, Security Rules può utilizzare i caratteri jolly per puntare a qualsiasi file con un prefisso di stringa specifico nel nome, incluse le barre, come in match /images/{imageId}.

Nell'esempio precedente, l'istruzione match utilizza la sintassi con carattere jolly {imageId}. Ciò significa che la regola si applica a qualsiasi file con /images/ all'inizio del nome, ad esempio /images/profilePhoto.png o /images/croppedProfilePhoto.png. Quando vengono valutate le espressioni allow nell'istruzione match, la variabile imageId viene risolta nel nome file dell'immagine, ad esempio profilePhoto.png o croppedProfilePhoto.png.

È possibile fare riferimento a una variabile con caratteri jolly dall'interno di match per fornire l'autorizzazione per il nome o il percorso del file:

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

Dati gerarchici

Come abbiamo detto in precedenza, non esiste una struttura gerarchica all'interno di un bucket Cloud Storage. Tuttavia, utilizzando una convenzione per i nomi file, spesso una che include barre nei nomi file, possiamo simulare una struttura che assomiglia a una serie nidificata di directory e sottodirectory. È importante capire come Firebase Security Rules interagisce con questi nomi file.

Prendiamo in considerazione la situazione di un insieme di file con nomi che iniziano tutti con la radice /images/. Firebase Security Rules si applica solo al nome file corrispondente, pertanto i controlli degli accessi definiti per lo stem /images/ non si applicano allo stem /mp3s/. Scrivi invece regole esplicite che corrispondano a diversi pattern di nomi file:

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      allow read, write: if <condition>;
    }

    // Explicitly define rules for the 'mp3s' pattern
    match /mp3s/{mp3Id} {
      allow read, write: if <condition>;
    }
  }
}

Quando nidifichi le istruzioni match, il percorso dell'istruzione match interna viene sempre aggiunto al percorso dell'istruzione match esterna. I seguenti due set di regole sono quindi equivalenti:

service firebase.storage {
  match /b/{bucket}/o {
    match /images {
      // Exact match for "images/profilePhoto.png"
      match /profilePhoto.png {
        allow write: if <condition>;
      }
    }
  }
}

service firebase.storage {
  match /b/{bucket}/o {
    // Exact match for "images/profilePhoto.png"
    match /images/profilePhoto.png {
      allow write: if <condition>;
      }
  }
}

Caratteri jolly di corrispondenza ricorsiva

Oltre ai caratteri jolly che corrispondono e restituiscono stringhe alla fine di un nome file, è possibile dichiarare un carattere jolly per più segmenti per una corrispondenza più complessa aggiungendo =** al nome del carattere jolly, ad esempio {path=**}:

// Partial match for files that start with "images"
match /images {

  // Exact match for "images/**"
  // e.g. images/users/user:12345/profilePhoto.png is matched
  // images/profilePhoto.png is also matched!
  match /{allImages=**} {
    // This rule matches one or more path segments (**)
    // allImages is a path that contains all segments matched
    allow read: if <other_condition>;
  }
}

Se un file corrisponde a più regole, il risultato è l'OR del risultato di tutte le valutazioni delle regole. In altre parole, se una regola corrispondente al file restituisce true, il risultato è true.

Nelle regole riportate sopra, il file "images/profilePhoto.png" può essere letto se condition o other_condition restituiscono true, mentre il file "images/users/user:12345/profilePhoto.png" è soggetto solo al risultato di other_condition.

Cloud Storage Security Rules non vengono applicate a cascata e le regole vengono valutate solo quando il percorso della richiesta corrisponde a un percorso con regole specificate.

rules_version = '2';
service cloud.storage {
  match /b/{bucket}/o {
   ...
 }
}

rules_version = '2';
service firebase.storage {
 match /b/{bucket}/o {
   // Matches any file in a songs "subdirectory" under the
   // top level of your Cloud Storage bucket.
   match /{prefixSegment=**}/songs/{mp3filenames} {
     allow read, write: if <condition>;
   }
  }
}

Operazioni granulari

In alcune situazioni, è utile suddividere read e write in operazioni più granulari. Ad esempio, l'app potrebbe voler applicare condizioni diverse per la creazione di file rispetto all'eliminazione di file.

Un'operazione read può essere suddivisa in get e list.

Una regola write può essere suddivisa in create, update e delete:

service firebase.storage {
  match /b/{bucket}/o {
    // A read rule can be divided into read and list rules
    match /images/{imageId} {
      // Applies to single file read requests
      allow get: if <condition>;
      // Applies to list and listAll requests (Security Rules Version 2)
      allow list: if <condition>;

    // A write rule can be divided into create, update, and delete rules
    match /images/{imageId} {
      // Applies to writes to file contents
      allow create: if <condition>;

      // Applies to updates to (pre-existing) file metadata
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
 }
}

Istruzioni di corrispondenza sovrapposte

È possibile che un nome file corrisponda a più di un'istruzione match. Nel caso in cui più espressioni allow corrispondano a una richiesta, l'accesso è consentito se una delle condizioni è true:

service firebase.storage {
  match b/{bucket}/o {
    // Matches file names directly inside of '/images/'.
    match /images/{imageId} {
      allow read, write: if false;
    }

    // Matches file names anywhere under `/images/`
    match /images/{imageId=**} {
      allow read, write: if true;
    }
  }
}

Nell'esempio precedente, tutte le letture e le scritture nei file il cui nome inizia con /images/ sono consentite perché la seconda regola è sempre true, anche quando la prima regola è false.

Le regole non sono filtri

Una volta protetti i dati e iniziate le operazioni sui file, tieni presente che le regole di sicurezza non sono filtri. Non puoi eseguire operazioni su un insieme di file corrispondenti a un pattern di nome file e aspettarti che Cloud Storage acceda solo ai file a cui il client corrente ha l'autorizzazione di accedere.

Ad esempio, considera la seguente regola di sicurezza:

service firebase.storage {
  match /b/{bucket}/o {
    // Allow the client to read files with contentType 'image/png'
    match /aFileNamePrefix/{aFileName} {
      allow read: if resource.contentType == 'image/png';
    }
  }
}

Rifiutata: questa regola rifiuta la seguente richiesta perché l'insieme di risultati può includere file in cui contentType non è image/png:

filesRef = storage.ref().child("aFilenamePrefix");

filesRef.listAll()
    .then(function(result) {
      console.log("Success: ", result.items);
    })
});

Le regole in Cloud Storage Security Rules valutano ogni query in base al suo potenziale risultato e non soddisfano la richiesta se potrebbe restituire un file che il client non ha l'autorizzazione di leggere. Le richieste di accesso devono rispettare i vincoli impostati dalle tue regole.

Passaggi successivi

Puoi approfondire la tua comprensione di Firebase Security Rules per Cloud Storage:

• Scopri il prossimo concetto principale del linguaggio delle regole, le condizioni dinamiche, che consentono alle regole di verificare l'autorizzazione dell'utente, confrontare i dati esistenti e in entrata, convalidare i dati in entrata e altro ancora.

• Esamina i casi d'uso tipici della sicurezza e le definizioni di Firebase Security Rules che li riguardano.

Puoi esplorare i casi d'uso di Firebase Security Rules specifici per Cloud Storage: