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 nei bucket Cloud Storage. La sintassi flessibile delle regole ti consente di creare regole per controllare qualsiasi operazione, dalle 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 relativa a servizi e database

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

service firebase.storage {
    // ...
}

La dichiarazione service firebase.storage delimita 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 es. lettura, scrittura) coinvolti e le condizioni in base alle quali l'accesso è consentito o negato.

Nel set di regole predefinito, la prima dichiarazione match utilizza un'espressione di carattere jolly {bucket} per indicare che le regole si applicano a tutti i bucket del progetto. Discuteremo più a fondo dell'idea delle partite con 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 rimandano a file. Un'istruzione di corrispondenza può fare riferimento a un file specifico, come in match /images/profilePhoto.png.

Corrispondenza di caratteri jolly

Oltre a fare riferimento a un singolo file, Rules può utilizzare i caratteri jolly per fare riferimento 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 dei caratteri 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 le espressioni allow nell'istruzione di corrispondenza vengono valutate, la variabile imageId viene risolta nel nome file dell'immagine, ad esempio profilePhoto.png o croppedProfilePhoto.png.

È possibile fare riferimento a una variabile jolly all'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, all'interno di un bucketCloud Storage non è presente alcuna struttura gerarchica. Tuttavia, utilizzando una convenzione di denominazione dei file, spesso con barre nei nomi dei file, possiamo simulare una struttura simile a una serie nidificata di directory e sottodirectory. È importante comprendere come Firebase Security Rules interagisce con questi nomi file.

Prendi in considerazione la situazione di un insieme di file con nomi che iniziano tutti con la radice/images/. Firebase Security Rules si applicano solo al nome file corrispondente, pertanto i controlli di accesso definiti per l'elemento principale /images/ non si applicano all'elemento principale /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 set 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 per le corrispondenze ricorsive

Oltre ai caratteri jolly che corrispondono e restituiscono stringhe alla fine di un nome file, è possibile dichiarare un carattere jolly con 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 è il OR del risultato di tutte le valutazioni delle regole. In altre parole, se una regola a cui corrisponde il file restituisce true, il risultato è true.

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

Cloud Storage Security Rules non si applicano in modo ricorsivo 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 alcuni casi, è utile suddividere read e write in operazioni più granulari. Ad esempio, la tua app potrebbe voler applicare condizioni diverse alla creazione dei file rispetto all'eliminazione.

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 (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 dei 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 aver 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 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 accesso.

Ad esempio, prendi in considerazione 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';
    }
  }
}

Rifiutato: questa regola rifiuta la seguente richiesta perché il set 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 la richiesta non va a buon fine se potrebbe restituire un file per cui il client non ha l'autorizzazione di lettura. Le richieste di accesso devono rispettare i vincoli impostati dalle tue regole.

Passaggi successivi

Per approfondire la conoscenza del Firebase Security Rules per Cloud Storage:

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

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

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