Strutturazione delle regole di sicurezza di Cloud Firestore

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

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

Dichiarazione di servizio e database

Le regole di sicurezza di Cloud Firestore iniziano sempre con la seguente dichiarazione:

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

La dichiarazione del service cloud.firestore le regole a Cloud Firestore, prevenendo conflitti tra le regole di sicurezza di Cloud Firestore e le regole per altri prodotti come Cloud Storage.

La dichiarazione match /databases/{database}/documents specifica che le regole devono corrispondere a qualsiasi database Cloud Firestore nel progetto. Attualmente ogni progetto ha un solo database denominato (default) .

Regole di lettura/scrittura di base

Le regole di base consistono in una dichiarazione di match che specifica un percorso del documento e un'espressione di allow che dettaglia 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 dichiarazioni di corrispondenza devono puntare a documenti, non a raccolte. Una dichiarazione di corrispondenza 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 collezione delle cities , come /cities/SF o /cities/NYC . Quando vengono valutate le espressioni di allow nella dichiarazione di corrispondenza, la variabile della city si risolverà nel nome del documento della città, ad esempio SF o NYC .

Operazioni granulari

In alcune situazioni, è utile suddividere la read e la write in operazioni più granulari. Ad esempio, la tua app potrebbe voler imporre condizioni diverse alla creazione del documento rispetto all'eliminazione del documento. Oppure potresti voler consentire la lettura di un singolo documento ma negare le query di grandi dimensioni.

Una regola di read può essere suddivisa in get e list , mentre una regola di write può essere suddivisa in create , update ed 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 sottoraccolte. È importante capire come le regole di sicurezza interagiscono con i dati gerarchici.

Si consideri la situazione in cui ogni documento nella raccolta delle cities contiene una sottoraccolta di landmarks di riferimento. Le regole di sicurezza si applicano solo al percorso abbinato, quindi i controlli di accesso definiti nella raccolta delle cities non si applicano alla sottoraccolta dei landmarks di riferimento. Invece, scrivi 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 si annidano le istruzioni di match , il percorso dell'istruzione di match interna è sempre relativo al percorso dell'istruzione di 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 arbitrariamente profonda, usa la sintassi ricorsiva dei caratteri jolly, {name=**} . Per 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 si utilizza la sintassi ricorsiva dei caratteri jolly, la variabile dei caratteri jolly conterrà l'intero segmento del percorso corrispondente, anche se il documento si trova in una sottoraccolta profondamente nidificata. Ad esempio, le regole sopra elencate corrisponderebbero a un documento che si trova in /cities/SF/landmarks/coit_tower e il valore della variabile del document sarebbe SF/landmarks/coit_tower .

Si noti, 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 query sui gruppi di raccolte , devi utilizzare la versione 2, vedi protezione delle query sui gruppi di raccolte .

Dichiarazioni di corrispondenza sovrapposte

È possibile che un documento corrisponda a più di una dichiarazione di match . Nel caso in cui più espressioni di allow corrispondano a una richiesta, l'accesso è consentito se una 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 sopra, tutte le letture e le scritture nella raccolta delle 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:

Prossimi passi

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