Buka konsol

Menyusun Aturan Keamanan Firestore Cloud

Dengan menggunakan Aturan Keamanan Cloud Firestore, Anda dapat mengontrol akses ke dokumen dan koleksi di database. Dengan sintaks aturan yang fleksibel, Anda dapat membuat aturan yang cocok dengan apa pun, dari penulisan ke seluruh database hingga operasi pada dokumen tertentu.

Panduan ini menjelaskan sintaks dasar dan struktur aturan keamanan. Gabungkan sintaks ini dengan condition aturan keamanan untuk membuat seperangkat aturan lengkap.

Deklarasi layanan dan database

Aturan Keamanan Cloud Firestore selalu dimulai dengan deklarasi berikut:

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

Deklarasi service cloud.firestore mencakup aturan untuk Cloud Firestore, sehingga mencegah konflik antara Aturan Keamanan Cloud Firestore dan aturan produk lain seperti Cloud Storage.

Deklarasi match /databases/{database}/documents menetapkan bahwa aturan harus cocok dengan database Cloud Firestore mana pun dalam project tersebut. Saat ini, setiap project hanya memiliki satu database yang disebut (default).

Aturan baca/tulis dasar

Aturan dasar terdiri dari pernyataan match yang menentukan lokasi dokumen dan ekspresi allow yang memerinci kapan pembacaan data tertentu diizinkan:

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

Semua pernyataan kecocokan harus mengarah ke dokumen, bukan koleksi. Pernyataan kecocokan dapat mengarah ke dokumen tertentu, seperti pada match /cities/SF atau menggunakan karakter pengganti untuk mengarah ke dokumen pada lokasi tertentu, seperti pada match /cities/{city}.

Pada contoh di atas, pernyataan kecocokan menggunakan sintaks karakter pengganti {city}. Hal ini berarti aturan tersebut berlaku untuk setiap dokumen pada koleksi cities, seperti /cities/SF atau /cities/NYC. Jika ekspresi allow pada pernyataan kecocokan dievaluasi, variabel city akan menentukan nama dokumen kota, misalnya SF atau NYC.

Operasi terperinci

Pada beberapa situasi, membagi read dan write menjadi beberapa operasi yang lebih terperinci merupakan tindakan tepat. Misalnya, aplikasi Anda mungkin ingin memberlakukan condition berbeda pada pembuatan dokumen dengan pada penghapusan dokumen. Atau, Anda mungkin ingin mengizinkan pembacaan dokumen tunggal, namun menolak kueri yang besar.

Aturan read dapat dibagi menjadi get dan list, sementara aturan write dapat dibagi menjadi create, update, dan 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>;
    }
  }
}

Data hierarkis

Data di Cloud Firestore disusun menjadi koleksi dokumen, dan setiap dokumen dapat memperluas hierarkinya hingga subkoleksi. Anda perlu memahami bagaimana aturan keamanan berinteraksi dengan data hierarkis.

Perhatikan situasi di mana setiap dokumen dalam koleksi cities berisi subkoleksi landmarks. Aturan keamanan hanya berlaku pada lokasi yang cocok, sehingga kontrol akses yang ditetapkan pada koleksi cities tidak berlaku untuk subkoleksi landmarks. Sebagai gantinya, tulis aturan eksplisit untuk mengontrol akses ke subkoleksi:

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

Jika pernyataan match dibuat bertingkat, lokasi pernyataan match dalam akan selalu bergantung pada lokasi pernyataan match luar. Oleh karena itu, kumpulan aturan berikut adalah setara:

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

Karakter pengganti rekursif

Jika Anda ingin menerapkan aturan hierarki dalam arbitrer, gunakan sintaks karakter pengganti rekursif, {name=**}. Contoh:

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

Saat menggunakan sintaks karakter pengganti rekursif, variabel karakter pengganti akan memuat seluruh segmen lokasi yang cocok, meskipun dokumen tersebut berada di subkoleksi bertingkat yang dalam. Misalnya, aturan yang tercantum di atas akan cocok dengan dokumen yang berada di /cities/SF/landmarks/coit_tower, dan nilai variabel document adalah SF/landmarks/coit_tower.

Namun, perlu diperhatikan bahwa perilaku karakter pengganti rekursif bergantung pada versi aturan.

Versi 1

Aturan keamanan menggunakan versi 1 secara default. Dalam versi 1, karakter pengganti rekursif cocok dengan satu atau beberapa item lokasi. Karakter pengganti tersebut tidak cocok dengan lokasi kosong, sehingga match /cities/{city}/{document=**} cocok dengan dokumen dalam subkoleksi, tetapi tidak cocok dalam koleksi cities, sedangkan match /cities/{document=**} cocok dengan kedua dokumen di koleksi dan subkoleksi cities.

Karakter pengganti rekursif harus ada di akhir pernyataan yang cocok.

Versi 2

Dalam aturan keamanan versi 2, karakter pengganti rekursif cocok dengan nol atau beberapa item lokasi. match/cities/{city}/{document=**} cocok dengan dokumen di setiap subkoleksi dan dokumen dalam koleksi cities.

Anda harus memilih versi 2 dengan menambahkan rules_version = '2'; di bagian atas aturan keamanan Anda:

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

Anda dapat memiliki paling banyak satu karakter pengganti rekursif di setiap pernyataan yang cocok, tetapi dalam versi 2, Anda dapat menempatkan karakter pengganti ini di mana saja dalam pernyataan yang cocok. Contoh:

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

Jika menggunakan kueri grup koleksi, Anda harus menggunakan versi 2. Lihat mengamankan kueri grup koleksi.

Pernyataan kecocokan yang tumpang tindih

Ada kemungkinan dokumen cocok dengan lebih dari satu pernyataan match. Jika beberapa ekspresi allow cocok dengan permintaan, akses akan diizinkan jika salah satu kondisi ini 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;
    }
  }
}

Pada contoh di atas, semua pembacaan dan penulisan ke koleksi cities akan diizinkan karena aturan keduanya selalu true, meskipun aturan pertamanya selalu false.

Batas aturan keamanan

Perhatikan batas berikut saat menangani aturan keamanan:

Batas Detail
Jumlah maksimum panggilan exists(), get(), dan getAfter() per permintaan
  • 10 untuk permintaan dokumen tunggal dan permintaan kueri.
  • 20 untuk pembacaan, transaksi, dan penulisan batch multi-dokumen. Batas 10 sebelumnya juga berlaku untuk setiap operasi.

    Misalnya, bayangkan Anda membuat permintaan penulisan batch dengan 3 operasi penulisan dan aturan keamanan yang menggunakan 2 panggilan akses dokumen untuk memvalidasi setiap penulisan. Dalam hal ini, setiap penulisan menggunakan 2 dari 10 panggilan aksesnya dan permintaan penulisan batch menggunakan 6 dari 20 panggilan aksesnya.

Melebihi salah satu batas akan menyebabkan error izin ditolak.

Beberapa panggilan akses dokumen dapat di-cache, dan panggilan yang di-cache tidak diperhitungkan batasnya.

Kedalaman maksimum panggilan fungsi 20
Jumlah maksimum panggilan rekursif atau fungsi siklis 0 &lpar;tidak diizinkan&rpar;
Jumlah maksimum ekspresi yang dievaluasi per permintaan 1.000
Ukuran maksimum kumpulan aturan 64 KB

Langkah berikutnya