Strutturazione delle regole di sicurezza di Cloud Firestore

Cloud Firestore Security Rules ti consente di controllare l'accesso ai documenti e raccolte nel database. La sintassi flessibile delle regole ti 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 e la struttura di base delle regole di sicurezza. Abbina questa sintassi alle condizioni delle regole di sicurezza per creare regole complete.

Dichiarazione relativa a servizi e database

Cloud Firestore Security Rules deve sempre iniziare con la seguente dichiarazione:

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

La dichiarazione service cloud.firestore delimita l'ambito delle regole a Cloud Firestore, evitando conflitti tra Cloud Firestore Security Rules 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. Al momento ogni progetto ha un solo database denominato (default).

Regole di lettura/scrittura di base

Le regole di base sono costituite da un'istruzione match che specifica un percorso documento e è consentita un'espressione allow che specifichi durante 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 di corrispondenza devono puntare a documenti, non a raccolte. Una corrispondenza l'istruzione può puntare a un documento specifico, ad esempio 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 dei caratteri jolly {city}. Ciò significa che la regola si applica a qualsiasi documento nella raccolta cities, ad esempio /cities/SF o /cities/NYC. Quando le espressioni allow nell'istruzione di corrispondenza vengono valutato, la variabile city si risolverà nel nome del documento della città, come SF o NYC.

Operazioni granulari

In alcuni casi, è utile suddividere read e write in operazioni più granulari. Ad esempio, la tua app potrebbe voler applicare alla creazione dei documenti che alla loro eliminazione. In alternativa, potresti consentire la lettura di singoli documenti, ma rifiutare le query di grandi dimensioni.

Una regola read può essere suddivisa in get e list, mentre una regola write può verrà suddiviso 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 sottocollezioni. È importante comprendere come le regole di sicurezza interagiscono con i dati gerarchici.

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

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 nidificano le istruzioni match, il percorso dell'istruzione match interna è sempre rispetto 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 vengano applicate a una gerarchia arbitrariamente profonda, utilizza sintassi con caratteri jolly ricorsivi, {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 si utilizza la sintassi con caratteri jolly ricorsivi, la variabile con caratteri jolly conterrà il carattere l'intero segmento di percorso corrispondente, anche se il documento si trova in una zona profondamente nidificata una sottoraccolta. Ad esempio, le regole elencate sopra corrispondono a un documento situato in /cities/SF/landmarks/coit_tower e il valore della variabile document è 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 sui gruppi di raccolte, devi utilizzare la versione 2. Consulta la sezione Proteggere le query sui gruppi di raccolte.

Estratti conto di corrispondenza sovrapposti

È possibile che un documento corrisponda a più di un'istruzione match. Nella nel caso in cui più espressioni 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 precedente, tutte le letture e le scritture nella raccolta cities saranno consentito perché la seconda regola è sempre true, anche se la prima è sempre false.

Limiti delle regole di sicurezza

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

Passaggi successivi

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