Check out what’s new from Firebase at Google I/O 2022. Learn more

Pelajari sintaks inti dari Aturan Keamanan Firebase untuk bahasa Cloud Storage

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

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

Deklarasi layanan dan database

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

service firebase.storage {
    // ...
}

Deklarasi service firebase.storage aturan ke Cloud Storage, 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 kecocokan yang menentukan nama file, dan ekspresi allow yang merinci saat membaca data yang ditentukan diizinkan. allow ekspresi menentukan metode akses (misalnya, baca, tulis) yang terlibat, dan kondisi di mana akses diizinkan atau ditolak.

Dalam kumpulan aturan default Anda, pernyataan match pertama menggunakan ekspresi karakter pengganti {bucket} untuk menunjukkan aturan berlaku untuk semua keranjang di proyek Anda. Kami akan membahas ide pertandingan wildcard lebih lanjut 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 menunjuk ke file. Pernyataan kecocokan dapat menunjuk ke file tertentu, seperti pada match /images/profilePhoto.png .

Cocokkan wildcard

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

Dalam contoh di atas, pernyataan kecocokan menggunakan sintaks wildcard {imageId} . Ini berarti aturan berlaku untuk file apa pun dengan /images/ di awal namanya, seperti /images/profilePhoto.png atau /images/croppedProfilePhoto.png . Saat ekspresi allow dalam pernyataan kecocokan dievaluasi, variabel imageId akan diubah menjadi nama file gambar, seperti profilePhoto.png atau croppedProfilePhoto.png .

Variabel wildcard dapat direferensikan 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";
}

Data hierarkis

Seperti yang kami katakan sebelumnya, tidak ada struktur hierarki di dalam bucket Cloud Storage. Tetapi dengan menggunakan konvensi penamaan file, sering kali yang menyertakan garis miring dalam nama file, kita dapat meniru struktur yang terlihat seperti serangkaian direktori dan subdirektori bersarang. Penting untuk memahami bagaimana Aturan Keamanan Firebase berinteraksi dengan nama file ini.

Pertimbangkan situasi sekumpulan file dengan nama yang semuanya dimulai dengan batang /images/ . Aturan Keamanan Firebase hanya berlaku pada nama file yang cocok, sehingga kontrol akses yang ditentukan pada batang /images/ tidak berlaku untuk batang /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 menyusun pernyataan match , jalur pernyataan match dalam selalu ditambahkan ke jalur pernyataan match luar. Oleh karena itu, dua aturan berikut ini 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>;
      }
  }
}

Wildcard pertandingan rekursif

Selain wildcard yang cocok dan mengembalikan string di akhir nama file, wildcard beberapa segmen dapat dideklarasikan untuk pencocokan yang lebih kompleks dengan menambahkan =** ke nama wildcard, 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 file, hasilnya adalah OR dari hasil semua evaluasi aturan. Artinya, jika ada aturan file yang cocok dengan nilai true , hasilnya adalah true .

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

Aturan Keamanan Cloud Storage tidak mengalir, dan aturan hanya dievaluasi saat jalur permintaan cocok dengan jalur dengan aturan yang ditentukan.

Versi 1

Aturan Keamanan Firebase menggunakan versi 1 secara default. Di versi 1, wildcard rekursif cocok dengan satu atau lebih elemen nama file, bukan nol atau lebih elemen. Jadi, match /images/{filenamePrefixWildcard}/{imageFilename=**} cocok dengan nama file seperti /images/profilePics/profile.png, tetapi bukan /images/badge.png. Gunakan /images/{imagePrefixorFilename=**} sebagai gantinya.

Wildcard rekursif harus ada di akhir pernyataan kecocokan.

Kami menyarankan Anda menggunakan versi 2 untuk fitur-fiturnya yang lebih canggih.

Versi 2

Di Aturan Keamanan Firebase versi 2, karakter pengganti rekursif cocok dengan nol atau beberapa item jalur. Jadi, /images/{filenamePrefixWildcard}/{imageFilename=**} cocok dengan nama file /images/profilePics/profile.png dan /images/badge.png.

Anda harus ikut serta ke 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 paling banyak satu karakter pengganti rekursif per pernyataan kecocokan, tetapi dalam versi 2, Anda dapat menempatkan karakter pengganti ini di mana saja dalam pernyataan kecocokan. Sebagai contoh:

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 granular

Dalam beberapa situasi, akan berguna untuk memecah read dan write menjadi operasi yang lebih terperinci. Misalnya, aplikasi Anda mungkin ingin menerapkan kondisi yang berbeda pada pembuatan file daripada pada penghapusan file.

Operasi read dapat dipecah menjadi get dan list .

Aturan write dapat dipecah 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 pertandingan yang tumpang tindih

Nama file mungkin cocok dengan lebih dari satu pernyataan match . Dalam kasus di mana beberapa ekspresi allow cocok dengan permintaan, akses diizinkan jika salah satu kondisinya true :

service firebase.storage {
  match b/{bucket}/o {
    // Matches any filename containing string '/images/'.
    match /images/{imageId} {
      allow read, write: if false;
    }

    // Matches all filenames containing string `/images/`
    match /images/{imageId=**} {
      allow read, write: if true;
    }
  }
}

Dalam contoh di atas, semua membaca dan menulis ke file dengan string /images/ di mana saja dalam nama file mereka akan diizinkan karena aturan kedua selalu true , meskipun aturan pertama selalu false .

Aturan bukan filter

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

Misalnya, ambil 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';
    }
  }
}

Denied : Aturan ini menolak permintaan berikut karena kumpulan hasil dapat menyertakan file di mana contentType 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 hasil potensialnya dan gagal permintaan jika dapat mengembalikan file yang klien tidak memiliki izin untuk membacanya. Permintaan akses harus mengikuti batasan yang ditetapkan oleh aturan Anda.

Langkah selanjutnya

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

  • Pelajari konsep utama berikutnya dari bahasa Aturan, kondisi dinamis , yang memungkinkan Aturan Anda memeriksa otorisasi pengguna, membandingkan data yang ada dan yang masuk, memvalidasi data yang masuk, dan banyak lagi.

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

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