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

Firebase Security Rules per Cloud Storage consentono di controllare l'accesso agli oggetti archiviati nei bucket 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.

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

Dichiarazione di servizi e database

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

service firebase.storage {
    // ...
}

La dichiarazione service firebase.storage limita le 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 es. 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 carattere jolly {bucket} per indicare che le regole si applicano a tutti i bucket del progetto. Parleremo maggiormente 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 di corrispondenza puntano a file. Un'istruzione di corrispondenza può puntare a un file specifico, come in match /images/profilePhoto.png.

Corrispondenza con caratteri jolly

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

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

È possibile fare riferimento a una variabile 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 prima, non esiste una struttura gerarchica all'interno di un bucket Cloud Storage. Tuttavia, utilizzando una convenzione di denominazione dei file, spesso una che include barre nei nomi dei file, possiamo imitare una struttura che assomiglia a una serie nidificata di directory e sottodirectory. È importante capire come Firebase Security Rules interagisce con questi nomi file.

Considera la situazione di un insieme di file i cui nomi iniziano tutti con la radice /images/. Firebase Security Rules si applicano solo al nome file corrispondente, pertanto i controlli di accesso definiti nel ramo /images/ non si applicano al ramo /mp3s/. Scrivi invece regole esplicite che corrispondano a pattern di nomi file diversi:

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. Pertanto, i seguenti due insiemi di regole sono 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 a 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 più regole corrispondono a un file, il risultato è l'OR del risultato di tutte le valutazioni delle regole. ovvero, se una regola a cui corrisponde il file restituisce true, il risultato è true.

Nelle regole riportate sopra, il file "images/profilePhoto.png" può essere letto se condition o other_condition restituiscono il valore 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.

Firebase Security Rules utilizza la versione 1 per impostazione predefinita. Nella versione 1, i caratteri jolly ricorsivi corrispondono a uno o più elementi del nome file, non a zero o più elementi. Pertanto, match /images/{filenamePrefixWildcard}/{imageFilename=**} corrisponde a un nome file come /images/profilePics/profile.png, ma non a /images/badge.png. Utilizza /images/{imagePrefixorFilename=**}.

I caratteri jolly ricorsivi devono essere inseriti alla fine di un'istruzione di corrispondenza.

Ti consigliamo di utilizzare la versione 2 per le sue funzionalità più potenti.

Nella versione 2 di Firebase Security Rules, i caratteri jolly ricorsivi corrispondono a zero o più elementi del percorso. Pertanto, /images/{filenamePrefixWildcard}/{imageFilename=**} corrisponde ai nomi dei file /images/profilePics/profile.png e /images/badge.png.

Devi attivare la versione 2 aggiungendo rules_version = '2'; all'inizio delle regole di sicurezza:

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

Puoi avere al massimo un carattere jolly ricorsivo per istruzione di corrispondenza, ma nella versione 2 puoi posizionarlo ovunque nell'istruzione di corrispondenza. Ad esempio:

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, la tua app potrebbe voler applicare condizioni diverse alla creazione e all'eliminazione dei file.

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

Cloud Storage

Una regola write può essere divisa 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 (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 qualsiasi 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

Dopo aver protetto i dati e iniziato a eseguire operazioni sui file, tieni presente che le regole di sicurezza non sono filtri. Non puoi eseguire operazioni su un insieme di file che corrispondono a un pattern di nomi di file e prevedere 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é il set di risultati può includere file in cui contentType non è image/png:

Web
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 potenziale risultato e non riescono a soddisfare la richiesta se potrebbero restituire un file che il client non ha l'autorizzazione a leggere. Le richieste di accesso devono rispettare i vincoli stabiliti 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 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 Firebase Security Rulesche li riguardano.

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