Structuration des règles de sécurité Cloud Firestore

Les règles de sécurité Cloud Firestore vous permettent de contrôler l'accès aux documents et collections de votre base de données. La syntaxe flexible des règles vous permet de créer des règles qui correspondent à tout, depuis toutes les écritures dans l'ensemble de la base de données jusqu'aux opérations sur un document spécifique.

Ce guide décrit la syntaxe et la structure de base des règles de sécurité. Combinez cette syntaxe avec des conditions de règles de sécurité pour créer des ensembles de règles complets.

Déclaration de service et de base de données

Les règles de sécurité Cloud Firestore commencent toujours par la déclaration suivante :

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

La déclaration du service cloud.firestore étend les règles à Cloud Firestore, évitant ainsi les conflits entre les règles de sécurité Cloud Firestore et les règles d'autres produits tels que Cloud Storage.

La déclaration match /databases/{database}/documents spécifie que les règles doivent correspondre à n'importe quelle base de données Cloud Firestore du projet. Actuellement, chaque projet n'a qu'une seule base de données nommée (default) .

Règles de lecture/écriture de base

Les règles de base consistent en une instruction match spécifiant un chemin d'accès au document et une expression allow détaillant quand la lecture des données spécifiées est autorisée :

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>;
    }
  }
}

Toutes les déclarations de correspondance doivent pointer vers des documents et non des collections. Une instruction match peut pointer vers un document spécifique, comme dans match /cities/SF ou utiliser des caractères génériques pour pointer vers n'importe quel document dans le chemin spécifié, comme dans match /cities/{city} .

Dans l'exemple ci-dessus, l'instruction match utilise la syntaxe générique {city} . Cela signifie que la règle s'applique à tout document de la collection cities , tel que /cities/SF ou /cities/NYC . Lorsque les expressions allow dans l'instruction match sont évaluées, la variable city sera résolue en nom de document de ville, tel que SF ou NYC .

Opérations granulaires

Dans certaines situations, il est utile de diviser read et write en opérations plus granulaires. Par exemple, votre application souhaitera peut-être appliquer des conditions différentes lors de la création de documents et lors de leur suppression. Ou vous souhaiterez peut-être autoriser la lecture d’un seul document mais refuser les requêtes volumineuses.

Une règle read peut être divisée en get et list , tandis qu'une règle write peut être divisée en create , update et 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>;
    }
  }
}

Données hiérarchiques

Les données dans Cloud Firestore sont organisées en collections de documents, et chaque document peut étendre la hiérarchie via des sous-collections. Il est important de comprendre comment les règles de sécurité interagissent avec les données hiérarchiques.

Prenons le cas où chaque document de la collection cities contient une sous-collection landmarks . Les règles de sécurité s'appliquent uniquement au chemin correspondant, de sorte que les contrôles d'accès définis sur la collection cities ne s'appliquent pas à la sous-collection de landmarks . Au lieu de cela, écrivez des règles explicites pour contrôler l'accès aux sous-collections :

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>;
        }
    }
  }
}

Lors de l'imbrication d'instructions match , le chemin de l'instruction match interne est toujours relatif au chemin de l'instruction match externe. Les ensembles de règles suivants sont donc équivalents :

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>;
    }
  }
}

Caractères génériques récursifs

Si vous souhaitez que les règles s'appliquent à une hiérarchie arbitrairement profonde, utilisez la syntaxe générique récursive, {name=**} . Par exemple:

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>;
    }
  }
}

Lors de l'utilisation de la syntaxe générique récursive, la variable générique contiendra l'intégralité du segment de chemin correspondant, même si le document se trouve dans une sous-collection profondément imbriquée. Par exemple, les règles répertoriées ci-dessus correspondraient à un document situé dans /cities/SF/landmarks/coit_tower , et la valeur de la variable document serait SF/landmarks/coit_tower .

Notez cependant que le comportement des caractères génériques récursifs dépend de la version des règles.

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>;
    }
  }
}

Si vous utilisez des requêtes de groupe de collecte , vous devez utiliser la version 2, voir sécurisation des requêtes de groupe de collection .

Déclarations de correspondance qui se chevauchent

Il est possible qu'un document corresponde à plusieurs instructions de match . Dans le cas où plusieurs expressions allow correspondent à une requête, l'accès est autorisé si l'une des conditions est 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;
    }
  }
}

Dans l'exemple ci-dessus, toutes les lectures et écritures dans la collection cities seront autorisées car la deuxième règle est toujours true , même si la première règle est toujours false .

Limites des règles de sécurité

Lorsque vous travaillez avec des règles de sécurité, notez les limites suivantes :

Prochaines étapes

• Écrivez des conditions de règles de sécurité personnalisées .
• Lisez la référence des règles de sécurité .