Utilizza le condizioni nelle regole di sicurezza di Firebase Cloud Storage

Questa guida si basa sulla guida Impara la sintassi di base del linguaggio Firebase Security Rules per mostrare come aggiungere condizioni a Firebase Security Rules per Cloud Storage.

L'elemento di base principale di Cloud Storage Security Rules è la condizione. Una condizione è un'espressione booleana che determina se una determinata operazione deve essere consentita o negata. Per le regole di base, l'utilizzo di valori letterali true e false come condizioni funziona perfettamente. Tuttavia, la Firebase Security Rules per il linguaggio Cloud Storage offre modi per scrivere condizioni più complesse che possono:

• Controlla l'autenticazione utente
• Convalida i dati in entrata

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.

Autenticazione

Firebase Security Rules per Cloud Storage si integra con Firebase Authentication per fornire un'efficace autenticazione basata sugli utenti per Cloud Storage. In questo modo è possibile un controllo dell'accesso granulare basato sulle attestazioni di un token Firebase Authentication.

Quando un utente autenticato esegue una richiesta per Cloud Storage, la variabile request.auth viene compilata con l'uid dell'utente (request.auth.uid) e con le attestazioni del JWT Firebase Authentication (request.auth.token).

Inoltre, quando utilizzi l'autenticazione personalizzata, vengono visualizzate rivendicazioni aggiuntive nel campo request.auth.token.

Quando un utente non autenticato esegue una richiesta, la variabile request.auth è null.

Utilizzando questi dati, esistono diversi modi comuni per utilizzare l'autenticazione per proteggere i file:

• Pubblico: ignora request.auth
• Autenticazione privata: verifica che request.auth non sia null
• Privato dell'utente: verifica che request.auth.uid sia uguale a un percorso uid
• Gruppo privato: controlla le rivendicazioni del token personalizzato per trovare una corrispondenza con una rivendicazione scelta o leggi i metadati del file per verificare se esiste un campo dei metadati

Pubblico

Qualsiasi regola che non tiene conto del contesto request.auth può essere considerata una regola public, poiché non tiene conto del contesto di autenticazione dell'utente. Queste regole possono essere utili per mostrare dati pubblici come asset di gioco, file audio o altri contenuti statici.

// Anyone to read a public image if the file is less than 100kB
// Anyone can upload a public file ending in '.txt'
match /public/{imageId} {
  allow read: if resource.size < 100 * 1024;
  allow write: if imageId.matches(".*\\.txt");
}

Autenticazione privata

In alcuni casi, potresti voler rendere i dati visualizzabili da tutti gli utenti autenticati della tua applicazione, ma non da quelli non autenticati. Poiché la variabile request.auth è null per tutti gli utenti non autenticati, per richiedere l'autenticazione è sufficiente verificare che la variabile request.auth esista:

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

Utente privato

Il caso d'uso di gran lunga più comune per request.auth sarà fornire ai singoli utenti autorizzazioni granulari sui loro file: dal caricamento delle immagini del profilo alla lettura di documenti privati.

Poiché i file in Cloud Storage hanno un "percorso" completo, per rendere un file controllato da un utente è sufficiente un'informazione identificativa univoca dell'utente nel prefisso del nome file (ad esempio l'uid dell'utente) che può essere controllata quando viene valutata la regola:

// Only a user can upload their profile picture, but anyone can view it
match /users/{userId}/profilePicture.png {
  allow read;
  allow write: if request.auth.uid == userId;
}

Gruppo privato

Un altro caso d'uso altrettanto comune è quello di consentire le autorizzazioni di gruppo su un oggetto, ad esempio consentire a più membri del team di collaborare su un documento condiviso. Esistono diversi approcci per farlo:

• Crea un token personalizzato Firebase Authentication che contiene informazioni aggiuntive su un membro del gruppo (ad esempio un ID gruppo)
• Includi le informazioni sul gruppo (ad esempio un ID gruppo o un elenco di uid autorizzati) nei metadati del file

Una volta archiviati questi dati nei metadati del token o del file, è possibile farvi riferimento all'interno di una regola:

// Allow reads if the group ID in your token matches the file metadata's `owner` property
// Allow writes if the group ID is in the user's custom token
match /files/{groupId}/{fileName} {
  allow read: if resource.metadata.owner == request.auth.token.groupId;
  allow write: if request.auth.token.groupId == groupId;
}

Richiedi valutazione

I caricamenti, i download, le modifiche ai metadati e le eliminazioni vengono valutati utilizzando il request inviato a Cloud Storage. Oltre all'ID univoco dell'utente e al payload Firebase Authentication nell'oggetto request.auth come descritto sopra, la variabile request contiene il percorso del file in cui viene eseguita la richiesta, l'ora in cui viene ricevuta la richiesta e il nuovo valore resource se la richiesta è di scrittura.

L'oggetto request contiene anche l'ID univoco dell'utente e il payload Firebase Authentication nell'oggetto request.auth, che verrà spiegato più dettagliatamente nella sezione Sicurezza basata sull'utente della documentazione.

Di seguito è riportato un elenco completo delle proprietà dell'oggetto request:

Valutazione delle risorse

Quando valuti le regole, potresti anche voler valutare i metadati del file che viene caricato, scaricato, modificato o eliminato. In questo modo puoi creare regole complesse e potenti che, ad esempio, consentono di caricare solo file con determinati tipi di contenuti o di eliminare solo file di dimensioni superiori a un determinato valore.

Firebase Security Rules per Cloud Storage fornisce i metadati del file nell'oggetto resource, che contiene coppie chiave/valore dei metadati mostrati in un oggetto Cloud Storage. Queste proprietà possono essere ispezionate nelle richieste read o write per garantire l'integrità dei dati.

Nelle richieste write (come caricamenti, aggiornamenti dei metadati ed eliminazioni), oltre all'oggetto resource, che contiene i metadati del file attualmente esistente nel percorso della richiesta, puoi anche utilizzare l'oggetto request.resource, che contiene un sottoinsieme dei metadati del file da scrivere se la scrittura è consentita. Puoi utilizzare questi due valori per garantire l'integrità dei dati o applicare vincoli dell'applicazione, come il tipo di file o le dimensioni.

Di seguito è riportato un elenco completo delle proprietà dell'oggetto resource:

request.resource contiene tutti questi elementi, ad eccezione di generation, metageneration, etag, timeCreated e updated.

Migliora con Cloud Firestore

Puoi accedere ai documenti in Cloud Firestore per valutare altri criteri di autorizzazione.

Utilizzando le funzioni firestore.get() e firestore.exists(), le regole di sicurezza possono valutare le richieste in entrata rispetto ai documenti in Cloud Firestore. Le funzioni firestore.get() e firestore.exists() prevedono entrambe percorsi dei documenti completamente specificati. Quando utilizzi le variabili per creare i percorsi per firestore.get() e firestore.exists(), devi eseguire l'escape esplicito delle variabili utilizzando la sintassi $(variable).

Nell'esempio seguente, vediamo una regola che limita l'accesso in lettura ai file agli utenti che sono membri di club particolari.

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{club}/files/{fileId} {
      allow read: if club in
        firestore.get(/databases/(default)/documents/users/$(request.auth.id)).data.memberships
    }
  }
}

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{userId}/photos/{fileId} {
      allow read: if
        firestore.exists(/databases/(default)/documents/users/$(userId)/friends/$(request.auth.id))
    }
  }
}

Dopo aver creato e salvato la prima Cloud Storage Security Rules che utilizza queste funzioni Cloud Firestore, ti verrà chiesto nella console Firebase o nell'interfaccia a riga di comando Firebase di abilitare le autorizzazioni per connettere i due prodotti.

Puoi disattivare la funzionalità rimuovendo un ruolo IAM, come descritto in Gestisci ed esegui il deployment di Firebase Security Rules.

Convalida i dati

Firebase Security Rules per Cloud Storage può essere utilizzato anche per la convalida dei dati, inclusa la convalida del nome e del percorso del file, nonché delle proprietà dei metadati del file, come contentType e size.

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      // Only allow uploads of any image file that's less than 5MB
      allow write: if request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

Funzioni personalizzate

Man mano che le Firebase Security Rules diventano più complesse, potresti voler raggruppare insiemi di condizioni in funzioni che puoi riutilizzare nel set di regole. Le regole di sicurezza supportano le funzioni personalizzate. La sintassi delle funzioni personalizzate è simile a quella di JavaScript, ma le funzioni Firebase Security Rules sono scritte in un linguaggio specifico di dominio che presenta alcune limitazioni importanti:

• Le funzioni possono contenere una sola istruzione return. Non possono contenere logica aggiuntiva. Ad esempio, non possono eseguire loop o chiamare servizi esterni.
• Le funzioni possono accedere automaticamente alle funzioni e alle variabili dall'ambito in cui sono definite. Ad esempio, una funzione definita nell'ambito service firebase.storage ha accesso alla variabile resource e, solo per Cloud Firestore, alle funzioni integrate come get() e exists().
• Le funzioni possono chiamare altre funzioni, ma non possono essere ricorsive. La profondità totale dello stack di chiamate è limitata a 10.
• Nella versione rules2, le funzioni possono definire variabili utilizzando la parola chiave let. Le funzioni possono avere un numero qualsiasi di associazioni let, ma devono terminare con un'istruzione return.

Una funzione viene definita con la parola chiave function e accetta zero o più argomenti. Ad esempio, potresti voler combinare i due tipi di condizioni utilizzati negli esempi precedenti in un'unica funzione:

service firebase.storage {
  match /b/{bucket}/o {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }
    match /images/{imageId} {
      allow read, write: if signedInOrPublic();
    }
    match /mp3s/{mp3Ids} {
      allow read: if signedInOrPublic();
    }
  }
}

L'utilizzo di funzioni in Firebase Security Rules ne semplifica la manutenzione man mano che la complessità delle regole aumenta.

Passaggi successivi

Dopo questa discussione sulle condizioni, hai una comprensione più sofisticata delle regole e sei in grado di:

Scopri come gestire i casi d'uso principali e il flusso di lavoro per lo sviluppo, il test e il deployment delle regole:

• Scrivi regole che affrontino scenari comuni.
• Amplia le tue conoscenze esaminando le situazioni in cui devi individuare ed evitare regole non sicure.
• Testa le regole utilizzando l'emulatore Cloud Storage e la libreria di test delle regole di sicurezza dedicata.
• Esamina i metodi disponibili per eseguire il deployment di Security Rules.