Mempelajari sintaksis inti bahasa Aturan Keamanan Firebase untuk Cloud Storage

Aturan Keamanan Firebase untuk Cloud Storage memungkinkan Anda mengontrol akses ke objek yang disimpan di bucket Cloud Storage. Sintaksis aturan yang fleksibel memungkinkan Anda membuat aturan untuk mengontrol operasi apa pun, dari semua penulisan ke bucket Cloud Storage Anda hingga operasi pada file tertentu.

Catatan: Bucket di Cloud Storage hanya berisi file, tidak berisi direktori. Pada halaman ini, Anda akan melihat garis miring / di nama file, seperti /images/profilePhoto.png, yang menunjukkan adanya hierarki berupa direktori dan subdirektori dalam bucket. Namun, nama file dapat mencakup awalan dengan garis miring yang memungkinkan Anda menentukan nama file unik yang terlihat seperti jalur direktori lengkap yang biasa berlaku dalam sistem file.

Panduan ini menjelaskan sintaksis dasar dan struktur dari Aturan Keamanan Cloud Storage untuk membuat kumpulan aturan lengkap.

Deklarasi layanan dan database

Aturan Keamanan Firebase untuk Cloud Storage selalu dimulai dengan deklarasi berikut:

service firebase.storage {
    // ...
}

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

Aturan baca/tulis dasar

Aturan dasar terdiri dari pernyataan match yang mengidentifikasi bucket Cloud Storage, pernyataan pencocokan yang menentukan nama file, dan ekspresi allow yang memerinci kapan pembacaan data tertentu diizinkan. Ekspresi allow menentukan metode akses (misalnya, baca, tulis) yang terlibat, dan kondisi yang mendasari diizinkan atau ditolaknya akses.

Dalam kumpulan aturan default Anda, pernyataan match pertama menggunakan ekspresi karakter pengganti {bucket} untuk menunjukkan aturan berlaku untuk semua bucket di project Anda. Kita akan membahas lebih lanjut kecocokan karakter pengganti di bagian berikutnya.

service firebase.storage {
  // The {bucket} wildcard indicates we match files in all Cloud Storage buckets
  match /b/{bucket}/o {
    // Match filename
    match /filename {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

Semua pernyataan kecocokan mengarah ke file. Pernyataan kecocokan dapat mengarah ke file tertentu, seperti pada match /images/profilePhoto.png.

Karakter pengganti kecocokan

Selain mengarah ke satu file, Aturan dapat menggunakan karakter pengganti untuk mengarah ke file apa pun yang memiliki awalan string dalam namanya, termasuk garis miring, seperti pada match /images/{imageId}.

Pada contoh di atas, pernyataan kecocokan menggunakan sintaksis karakter pengganti {imageId}. Artinya, aturan berlaku untuk file apa pun dengan /images/ di bagian awal namanya, seperti /images/profilePhoto.png atau /images/croppedProfilePhoto.png. Saat ekspresi allow dalam pernyataan kecocokan dievaluasi, variabel imageId akan me-resolve ke nama file gambar, seperti profilePhoto.png atau croppedProfilePhoto.png.

Variabel karakter pengganti dapat dirujuk dari dalam match untuk memberikan nama file atau otorisasi jalur:

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

Catatan: Pengguna hanya dapat mengakses file yang diizinkan secara khusus oleh Aturan Keamanan Firebase Anda. Misalnya, aturan yang ditampilkan di atas hanya mengizinkan akses ke file dengan /images/ di bagian awal namanya. Akibatnya, aturan tersebut juga menolak akses ke file dengan awalan nama file yang berbeda.

Data hierarkis

Seperti yang sudah dibahas sebelumnya, tidak ada struktur hierarkis di dalam bucket Cloud Storage. Namun, dengan menggunakan konvensi pemberian nama file, biasanya yang menyertakan garis miring dalam nama file, kita dapat meniru struktur yang terlihat seperti rangkaian direktori dan subdirektori bertingkat. Penting untuk memahami interaksi Aturan Keamanan Firebase dengan nama file ini.

Pikirkan kumpulan file dengan nama yang semuanya dimulai dengan stem /images/. Aturan Keamanan Firebase hanya berlaku pada nama file yang cocok, sehingga kontrol akses yang ditentukan pada stem /images/ tidak berlaku untuk stem /mp3s/. Sebagai gantinya, tulis aturan eksplisit yang cocok dengan pola nama file yang berbeda:

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      allow read, write: if <condition>;
    }

    // Explicitly define rules for the 'mp3s' pattern
    match /mp3s/{mp3Id} {
      allow read, write: if <condition>;
    }
  }
}

Saat membuat pernyataan match bertingkat, jalur pernyataan match dalam selalu ditambahkan ke jalur pernyataan match luar. Oleh karena itu, dua kumpulan aturan berikut adalah setara:

service firebase.storage {
  match /b/{bucket}/o {
    match /images {
      // Exact match for "images/profilePhoto.png"
      match /profilePhoto.png {
        allow write: if <condition>;
      }
    }
  }
}

service firebase.storage {
  match /b/{bucket}/o {
    // Exact match for "images/profilePhoto.png"
    match /images/profilePhoto.png {
      allow write: if <condition>;
      }
  }
}

Karakter pengganti kecocokan berulang

Selain karakter pengganti yang cocok dan menampilkan string di akhir nama file, beberapa karakter pengganti segmen dapat dideklarasikan untuk pencocokan yang lebih kompleks dengan menambahkan =** ke nama karakter pengganti, seperti {path=**}:

// Partial match for files that start with "images"
match /images {

  // Exact match for "images/**"
  // e.g. images/users/user:12345/profilePhoto.png is matched
  // images/profilePhoto.png is also matched!
  match /{allImages=**} {
    // This rule matches one or more path segments (**)
    // allImages is a path that contains all segments matched
    allow read: if <other_condition>;
  }
}

Jika beberapa aturan cocok dengan sebuah file, hasilnya adalah OR dari hasil semua evaluasi aturan. Artinya, jika aturan yang cocok dengan file bernilai true, hasilnya adalah true.

Pada aturan di atas, file "images/profilePhoto.png" dapat dibaca jika salah satu dari condition atau other_condition bernilai benar, sedangkan file "images/users/user:12345/profilePhoto.png" hanya bergantung pada hasil other_condition.

Aturan Keamanan Cloud Storage tidak menurun dan aturan hanya dievaluasi jika jalur permintaan cocok dengan jalur untuk aturan yang ditetapkan.

Versi 1

Aturan Keamanan Firebase menggunakan versi 1 secara default. Dalam versi 1, karakter pengganti berulang cocok dengan satu elemen nama file atau lebih, bukan nol elemen atau lebih. Oleh karena itu, match /images/{filenamePrefixWildcard}/{imageFilename=**} cocok dengan nama file seperti /images/profilePics/profile.png, tetapi bukan /images/badge.png. Sebagai gantinya, gunakan /images/{imagePrefixorFilename=**}.

Karakter pengganti berulang harus ada di akhir pernyataan yang cocok.

Sebaiknya gunakan versi 2 untuk menggunakan fiturnya yang lebih canggih.

Versi 2

Dalam Aturan Keamanan Firebase versi 2, karakter pengganti berulang cocok dengan nol item jalur atau lebih. Oleh karena itu, /images/{filenamePrefixWildcard}/{imageFilename=**} cocok dengan nama file /images/profilePics/profile.png dan /images/badge.png.

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

rules_version = '2';
service cloud.storage {
  match /b/{bucket}/o {
   ...
 }
}

Anda dapat memiliki maksimal satu karakter pengganti berulang di setiap pernyataan yang cocok, tetapi dalam versi 2 Anda dapat menempatkan karakter pengganti ini di mana saja dalam pernyataan yang cocok. Misalnya:

rules_version = '2';
service firebase.storage {
 match /b/{bucket}/o {
   // Matches any file in a songs "subdirectory" under the
   // top level of your Cloud Storage bucket.
   match /{prefixSegment=**}/songs/{mp3filenames} {
     allow read, write: if <condition>;
   }
  }
}

Operasi terperinci

Dalam beberapa situasi, ada baiknya kita membagi-bagi read dan write menjadi operasi yang lebih terperinci. Misalnya, aplikasi Anda mungkin ingin menerapkan kondisi yang berbeda pada pembuatan file dibandingkan dengan penghapusan file.

Operasi read dapat dibagi menjadi get dan list.

Catatan: Operasi Aturan list dan Cloud Storage List API hanya tersedia dalam project yang menggunakan Aturan Versi 2.

Aturan write dapat dibagi menjadi create, update, dan delete:

service firebase.storage {
  match /b/{bucket}/o {
    // A read rule can be divided into read and list rules
    match /images/{imageId} {
      // Applies to single file read requests
      allow get: if <condition>;
      // Applies to list and listAll requests (Rules Version 2)
      allow list: if <condition>;

    // A write rule can be divided into create, update, and delete rules
    match /images/{imageId} {
      // Applies to writes to file contents
      allow create: if <condition>;

      // Applies to updates to (pre-existing) file metadata
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
 }
}

Pernyataan kecocokan yang tumpang tindih

Satu nama file mungkin cocok dengan beberapa pernyataan match. Jika beberapa ekspresi allow cocok dengan suatu permintaan, akses akan diizinkan jika salah satu kondisi tersebut adalah true:

service firebase.storage {
  match b/{bucket}/o {
    // Matches file names directly inside of '/images/'.
    match /images/{imageId} {
      allow read, write: if false;
    }

    // Matches file names anywhere under `/images/`
    match /images/{imageId=**} {
      allow read, write: if true;
    }
  }
}

Pada contoh di atas, semua operasi baca dan tulis ke file yang namanya diawali dengan /images/ diizinkan karena aturan kedua selalu true, meskipun aturan pertama adalah false.

Aturan bukanlah filter

Setelah Anda mengamankan data dan mulai menjalankan operasi file, perlu diingat bahwa aturan keamanan bukanlah filter. Anda tidak dapat menjalankan operasi pada kumpulan file yang cocok dengan pola nama file dan mengharapkan Cloud Storage hanya mengakses file yang dapat diakses oleh klien saat ini.

Misalnya, perhatikan aturan keamanan berikut:

service firebase.storage {
  match /b/{bucket}/o {
    // Allow the client to read files with contentType 'image/png'
    match /aFileNamePrefix/{aFileName} {
      allow read: if resource.contentType == 'image/png';
    }
  }
}

Ditolak: Aturan ini menolak permintaan berikut karena kumpulan hasilnya dapat menyertakan file yang contentType-nya bukan image/png:

Web

filesRef = storage.ref().child("aFilenamePrefix");

filesRef.listAll()
    .then(function(result) {
      console.log("Success: ", result.items);
    })
});

Aturan di Aturan Keamanan Cloud Storage mengevaluasi setiap kueri terhadap kemungkinan hasilnya dan menggagalkan permintaan jika dapat menampilkan file yang tidak diizinkan untuk dibaca klien. Permintaan akses harus mengikuti batasan yang ditetapkan oleh aturan Anda.

Langkah berikutnya

Anda dapat memperdalam pemahaman tentang Aturan Keamanan Firebase untuk Cloud Storage:

• Pelajari konsep utama berikutnya untuk bahasa Aturan, conditions dinamis, yang memungkinkan Aturan Anda memeriksa otorisasi pengguna, membandingkan data yang sudah ada dan data yang masuk, memvalidasi data yang masuk, dan lainnya.

• Tinjau kasus penggunaan keamanan umum dan definisi Aturan Keamanan Firebase yang mengatasinya.

Anda dapat mempelajari kasus penggunaan Aturan Keamanan Firebase yang spesifik untuk Cloud Storage: