Strutturazione delle regole di sicurezza di Cloud Firestore

Cloud Firestore Security Rules ti consentono di controllare l'accesso a documenti e raccolte nel tuo database. La sintassi flessibile delle regole ti consente di creare regole che corrispondono a qualsiasi elemento, da tutte le operazioni di scrittura all'intero database fino alle operazioni su un documento specifico.

Questa guida descrive la sintassi e la struttura di base delle regole di sicurezza. Combina questa sintassi con le condizioni delle regole di sicurezza per creare set di regole completi.

Dichiarazione su servizi e database

Cloud Firestore Security Rules iniziano sempre con la seguente dichiarazione:

service cloud.firestore {
  // The {database} wildcard allows the rules to reference any database,
  // but these rules are only active on databases where they are explicitly deployed.
  match /databases/{database}/documents {
    // ...
  }
}

La dichiarazione service cloud.firestore limita le regole a Cloud Firestore, impedendo conflitti tra Cloud Firestore Security Rules e regole per altri prodotti come Cloud Storage.

La dichiarazione match /databases/{database}/documents specifica che le regole devono corrispondere a qualsiasi Cloud Firestore database nel progetto. Sebbene un progetto possa contenere fino a 100 database, solo il primo database creato viene designato come predefinito.

Cloud Firestore Security Rules vengono applicate separatamente per ogni database denominato nel tuo progetto. Ciò significa che se crei più database, devi gestire e implementare le regole per ognuno di essi singolarmente. Per istruzioni dettagliate sull'implementazione degli aggiornamenti, vedi Implementare gli aggiornamenti.

Regole di lettura/scrittura di base

Le regole di base sono costituite da un'istruzione match che specifica un percorso del documento e da un'espressione allow che descrive quando è consentita la lettura dei dati specificati:

service cloud.firestore {
  match /databases/{database}/documents {

    // Match any document in the 'cities' collection
    match /cities/{city} {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

Tutte le istruzioni match devono puntare ai documenti, non alle raccolte. Un'istruzione match può puntare a un documento specifico, come in match /cities/SF, o utilizzare caratteri jolly per puntare a qualsiasi documento nel percorso specificato, come in match /cities/{city}.

Nell'esempio precedente, l'istruzione match utilizza la sintassi del carattere jolly {city}. Ciò significa che la regola si applica a qualsiasi documento nella raccolta cities, ad esempio /cities/SF o /cities/NYC. Quando vengono valutate le espressioni allow nell'istruzione match, la variabile city viene risolta nel nome del documento della città, ad esempio SF o NYC.

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 documenti. In alternativa, potresti voler consentire le letture di singoli documenti, ma negare le query di grandi dimensioni.

Una regola read può essere suddivisa in get e list, mentre una regola write può essere suddivisa in create, update e delete:

service cloud.firestore {
  match /databases/{database}/documents {
    // A read rule can be divided into get and list rules

    match /cities/{city} {
      // Applies to single document read requests
      allow get: if <condition>;

      // Applies to queries and collection read requests
      allow list: if <condition>;
    }
    // A write rule can be divided into create, update, and delete rules
    match /cities/{city} {
      // Applies to writes to nonexistent documents
      allow create: if <condition>;

      // Applies to writes to existing documents
      allow update: if <condition>;

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

Dati gerarchici

I dati in Cloud Firestore sono organizzati in raccolte di documenti e ogni documento può estendere la gerarchia tramite le sottoraccolte. È importante capire come le regole di sicurezza interagiscono con i dati gerarchici.

Considera la situazione in cui ogni documento nella raccolta cities contiene una sottoraccolta landmarks. Le regole di sicurezza si applicano solo al percorso corrispondente, quindi i controlli di accesso definiti nella raccolta cities non si applicano alla sottoraccolta landmarks. Scrivi invece regole esplicite per controllare l'accesso alle sottoraccolte:

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      allow read, write: if <condition>;

        // Explicitly define rules for the 'landmarks' subcollection
        match /landmarks/{landmark} {
          allow read, write: if <condition>;
        }
    }
  }
}

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

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      match /landmarks/{landmark} {
        allow read, write: if <condition>;
      }
    }
  }
}

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city}/landmarks/{landmark} {
      allow read, write: if <condition>;
    }
  }
}

Caratteri jolly ricorsivi

Se vuoi che le regole si applichino a una gerarchia di profondità arbitraria, utilizza la sintassi del carattere jolly ricorsivo, {name=**}. Ad esempio:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

Quando utilizzi la sintassi del carattere jolly ricorsivo, la variabile del carattere jolly conterrà l'intero segmento di percorso corrispondente, anche se il documento si trova in una sottoraccolta nidificata in profondità. Ad esempio, le regole elencate sopra corrisponderebbero a un documento che si trova in /cities/SF/landmarks/coit_tower, e il valore di la variabile document sarebbe SF/landmarks/coit_tower.

Tieni presente, tuttavia, che il comportamento dei caratteri jolly ricorsivi dipende dalla versione delle regole.

rules_version = '2';
service cloud.firestore {
 match /databases/{database}/documents {
   // Matches any document in the cities collection as well as any document
   // in a subcollection.
   match /cities/{city}/{document=**} {
     allow read, write: if <condition>;
   }
 }
}

rules_version = '2';
service cloud.firestore {
 match /databases/{database}/documents {
   // Matches any document in the songs collection group
   match /{path=**}/songs/{song} {
     allow read, write: if <condition>;
   }
 }
}

Se utilizzi le query di gruppo di raccolte , devi utilizzare la versione 2. Per maggiori informazioni, consulta la sezione Proteggere le query di gruppo di raccolte .

Istruzioni match sovrapposte

È possibile che un documento 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 cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the 'cities' collection.
    match /cities/{city} {
      allow read, write: if false;
    }

    // Matches any document in the 'cities' collection or subcollections.
    match /cities/{document=**} {
      allow read, write: if true;
    }
  }
}

Nell'esempio precedente, tutte le operazioni di lettura e scrittura nella raccolta cities saranno consentite perché la seconda regola è sempre true, anche se la prima regola è sempre false.

Limiti delle regole di sicurezza

Quando lavori con le regole di sicurezza, tieni presente i seguenti limiti:

Passaggi successivi

• Scrivi condizioni delle regole di sicurezza personalizzate.
• Leggi il riferimento alle regole di sicurezza.