Aturan Keamanan untuk operasi Pipeline

Aturan Keamanan untuk operasi Pipeline

Aturan operasi Pipeline memungkinkan Anda mencocokkan kemampuan pemfilteran mesin Aturan yang ada. Meskipun operasi Pipeline menawarkan serangkaian fitur yang lengkap, mesin Aturannya dibatasi untuk mengenali filter sederhana guna memastikan pemenuhan dan keamanan kueri.

Persyaratan edisi dan mode

Dokumen ini berlaku untuk edisi Firestore Enterprise dalam mode Native.

Ekspresi Filter yang Didukung

Agar kueri dibatasi oleh aturan Anda, kueri tersebut harus menggunakan operator perbandingan standar terhadap konstanta. Jenis filter berikut dikenali oleh mesin Aturan:

• Persamaan dan Pertidaksamaan: eq, neq.
• Perbandingan: gt, gte, lt, lte.
• Himpunan: in, arrayContains.

Berikut beberapa contohnya:

• where(eq("foo", 2))
• where(lt("foo", 2))
• documents("/user/1", "/user/2").where(...)

Catatan: Ekspresi kompleks, seperti aritmetika dalam filter (misalnya, where(eq("foo" * 2, 10))) atau fungsi string seperti strContains, tidak dikenali untuk pembatasan kueri.

Properti Permintaan

Anda dapat terus menggunakan objek request untuk memvalidasi autentikasi dan konteks kueri, meskipun beberapa properti yang tersedia dalam kueri standar tidak didukung dalam pipeline.

Properti yang didukung

Mesin baru ini tetap mendukung properti berikut:

• request.auth: Mengakses data token dan UID pengguna.
• request.method: Mengidentifikasi operasi (Misalnya, get, list).
• request.path: Jalur resource yang diakses.
• request.time: Stempel waktu sisi server dari permintaan.

Properti yang tidak didukung

Properti request.query seperti limit, offset, dan orderBy tidak didukung untuk pemeriksaan aturan Pipeline karena kompleksitas penentuan nilai ini dalam kueri yang terdiri dari beberapa tahap.

Penanganan dan izin tahap pipeline

Ada berbagai tahap pipeline yang dipetakan ke operasi terperinci tertentu dalam aturan keamanan:

• Izin allow list: Dipicu oleh tahap collection(), collectionGroup(), dan database().
• Izin allow get: Dipicu oleh tahap documents(), yang diperlakukan serupa dengan operasi get batch.
• Izin allow create: Dipicu oleh tahap insert(), dan tahap upsert() saat membuat dokumen baru.
• Izin allow update: Dipicu oleh tahap update(), dan tahap upsert() saat memperbarui dokumen yang ada.
• Izin allow delete: Dipicu oleh tahap delete().
• Izin allow write: Berlaku untuk semua operasi DML (insert(), update(), upsert(), dan delete()).
• Tahap modifikasi kolom: Aturan hanya berlaku pada data yang disimpan, bukan nilai turunan. Jika pipeline mencakup tahap yang mengubah kolom (Misalnya, AddFields, ReplaceWith, Select), mesin Aturan akan berhenti menerapkan batasan filter setelah mencapai tahap tersebut.
• Tahap literals: Tahap literals() tidak melakukan pembacaan dari database, tetapi dapat menimbulkan biaya. Untuk mencegah penyalahgunaan, tahap ini harus dipasangkan dengan tahap lain (seperti collection()) yang dapat diverifikasi oleh aturan.

Tahap bahasa pengolahan data (DML) dan Aturan Keamanan

Saat menjalankan tahap Bahasa pengolahan data (DML) (insert(), update(), upsert(), dan delete()), Aturan Keamanan mengevaluasi izin secara berbeda dibandingkan dengan kueri baca:

• Evaluasi aturan per dokumen: Tidak seperti pipeline baca, yang memerlukan ekspresi filter di awal untuk membatasi kueri pada waktu perencanaan, operasi DML mengevaluasi aturan keamanan terhadap setiap mutasi dokumen.
• Variabel aturan:
  • request.resource: Berisi data dokumen yang diusulkan untuk operasi insert(), update(), dan upsert().
  • resource: Berisi data dokumen saat ini yang disimpan dalam database sebelum modifikasi (tersedia untuk update(), delete(), dan upsert() dokumen yang ada).

Batas sistem dan perilaku eksekusi dengan DML

Saat menjalankan operasi DML dengan Aturan Keamanan, perhatikan batas sistem dan perilaku eksekusi berikut:

Batas dua puluh pencarian di get() dan exists()

Aturan Keamanan Firebase mengizinkan maksimum 20 pencarian dokumen (get() atau exists()) di seluruh permintaan.

Saat pipeline DML berjalan di luar transaksi eksplisit, dokumen akan diproses dalam batch. Karena setiap batch dijalankan dalam transaksinya sendiri dan dokumen dapat diubah secara serentak di antara batch, aturan keamanan dan pencarian dokumen akan dievaluasi ulang untuk setiap batch operasi tulis.

Meskipun aturan keamanan Anda mengevaluasi satu dokumen statis, misalnya, memeriksa apakah pengguna adalah administrator:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /posts/{postId} {
      allow write: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.isAdmin == true;
    }
  }
}

Setiap batch penulisan dokumen melakukan pencarian. Akibatnya, setelah menulis semua dokumen yang memungkinkan, batas 20 pencarian untuk permintaan tercapai, dan pipeline gagal dengan error PERMISSION_DENIED. Selain itu, setiap pencarian yang dilakukan per batch tulis akan dikenai biaya penagihan baca tersendiri.

Tips: Untuk menghindari batas 20 pencarian pada operasi DML massal, gunakan Klaim Kustom pada token Firebase Authentication (misalnya, request.auth.token.isAdmin == true), bukan pencarian get() atau exists(). Klaim kustom divalidasi dalam memori langsung dari token autentikasi, sehingga sepenuhnya menghindari pembacaan dokumen dan batas pencarian.

Berhasil sebagian dan PERMISSION_DENIED

Saat dijalankan di luar transaksi, operasi DML meng-commit penulisan dalam batch berurutan. Jika batch gagal—baik karena dokumen gagal memenuhi kondisi aturan atau karena batas 20 pencarian terlampaui—pipeline akan berhenti dan menampilkan error PERMISSION_DENIED.

Namun, batch yang telah di-commit tidak akan di-roll back. Database tetap dalam status diperbarui sebagian. Karena klien menerima error tanpa daftar dokumen yang diubah, Anda harus mengkueri data untuk memeriksa penulisan mana yang berhasil.

Tips: Jika workload Anda memerlukan eksekusi semua atau tidak sama sekali, jalankan pipeline DML dalam transaksi pengguna eksplisit (misalnya, menggunakan runTransaction dan transaction.execute(pipeline)). Dalam transaksi, semua operasi akan di-commit bersama atau di-roll back sepenuhnya jika terjadi error. Perhatikan bahwa transaksi tunduk pada batas transaksi edisi Firestore Enterprise.

Mendiagnosis kegagalan aturan dengan Cloud Audit Logs

Demi alasan keamanan, error PERMISSION_DENIED yang ditampilkan kepada klien tidak mengungkapkan kondisi aturan keamanan mana yang gagal atau apakah batas 20 pencarian telah tercapai.

Untuk mendiagnosis kegagalan evaluasi aturan, administrator project dapat memeriksa Cloud Audit Logs di konsol Google Cloud (di bagian Firestore > Monitoring atau di Logs Explorer) untuk melihat entri EvaluationError yang mendetail.