Gunakan ketentuan dalam Aturan Keamanan Penyimpanan Cloud Firebase

Panduan ini dibuat berdasarkan mempelajari sintaks inti dari panduan bahasa Aturan Keamanan Firebase untuk menunjukkan cara menambahkan ketentuan ke Aturan Keamanan Firebase untuk Cloud Storage.

Blok penyusun utama Aturan Keamanan Cloud Storage adalah kondisinya . Kondisi adalah ekspresi boolean yang menentukan apakah operasi tertentu harus diizinkan atau ditolak. Untuk aturan dasar, menggunakan literal true dan false sebagai kondisi bekerja dengan sangat baik. Tetapi bahasa Aturan Keamanan Firebase untuk Cloud Storage memberi Anda cara untuk menulis kondisi yang lebih kompleks yang dapat:

  • Periksa otentikasi pengguna
  • Validasi data yang masuk

Autentikasi

Aturan Keamanan Firebase untuk Cloud Storage terintegrasi dengan Firebase Authentication untuk menyediakan autentikasi berbasis pengguna yang andal ke Cloud Storage. Hal ini memungkinkan kontrol akses granular berdasarkan klaim token Firebase Authentication.

Saat pengguna yang diautentikasi melakukan permintaan terhadap Cloud Storage, variabel request.auth diisi dengan uid pengguna ( request.auth.uid ) serta klaim Firebase Authentication JWT ( request.auth.token ).

Selain itu, saat menggunakan autentikasi khusus, klaim tambahan akan muncul di bidang request.auth.token .

Saat pengguna yang tidak diautentikasi melakukan permintaan, variabel request.auth adalah null .

Dengan menggunakan data ini, ada beberapa cara umum untuk menggunakan otentikasi untuk mengamankan file:

  • Publik: abaikan request.auth
  • Pribadi yang diautentikasi: periksa apakah request.auth bukan null
  • Pribadi pengguna: periksa apakah request.auth.uid sama dengan path uid
  • Pribadi grup: periksa klaim token khusus untuk mencocokkan klaim yang dipilih, atau baca metadata file untuk melihat apakah ada bidang metadata

Publik

Aturan apa pun yang tidak mempertimbangkan konteks request.auth dapat dianggap sebagai aturan public , karena tidak mempertimbangkan konteks otentikasi pengguna. Aturan ini dapat berguna untuk menampilkan data publik seperti aset game, file suara, atau konten statis lainnya.

// Anyone to read a public image if the file is less than 100kB
// Anyone can upload a public file ending in '.txt'
match /public/{imageId} {
  allow read: if resource.size < 100 * 1024;
  allow write: if imageId.matches(".*\\.txt");
}

Pribadi yang diautentikasi

Dalam kasus tertentu, Anda mungkin ingin data dapat dilihat oleh semua pengguna aplikasi yang diautentikasi, tetapi tidak oleh pengguna yang tidak diautentikasi. Karena variabel request.auth adalah null untuk semua pengguna yang tidak diautentikasi, yang harus Anda lakukan adalah memeriksa apakah variabel request.auth ada untuk meminta otentikasi:

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

Pribadi pengguna

Sejauh ini, kasus penggunaan yang paling umum untuk request.auth adalah memberikan izin terperinci kepada pengguna individu pada file mereka: mulai dari mengunggah gambar profil hingga membaca dokumen pribadi.

Karena file di Cloud Storage memiliki "jalur" lengkap ke file tersebut, yang diperlukan untuk membuat file yang dikendalikan oleh pengguna adalah bagian dari informasi pengenal pengguna yang unik di awalan nama file (seperti uid pengguna) yang dapat diperiksa ketika aturan dievaluasi:

// Only a user can upload their profile picture, but anyone can view it
match /users/{userId}/profilePicture.png {
  allow read;
  allow write: if request.auth.uid == userId;
}

Grup pribadi

Kasus penggunaan lain yang sama-sama umum adalah untuk mengizinkan izin grup pada suatu objek, seperti mengizinkan beberapa anggota tim untuk berkolaborasi pada dokumen bersama. Ada beberapa pendekatan untuk melakukan ini:

  • Buat token kustom Firebase Authentication yang berisi informasi tambahan tentang anggota grup (seperti ID grup)
  • Sertakan informasi grup (seperti ID grup atau daftar uid resmi) dalam metadata file

Setelah data ini disimpan dalam token atau metadata file, data ini dapat dirujuk dari dalam aturan:

// Allow reads if the group ID in your token matches the file metadata's `owner` property
// Allow writes if the group ID is in the user's custom token
match /files/{groupId}/{fileName} {
  allow read: if resource.metadata.owner == request.auth.token.groupId;
  allow write: if request.auth.token.groupId == groupId;
}

Permintaan Evaluasi

Upload, download, perubahan metadata, dan penghapusan dievaluasi menggunakan request yang dikirim ke Cloud Storage. Selain ID unik pengguna dan payload Firebase Authentication di objek request.auth seperti dijelaskan di atas, variabel request berisi jalur file tempat permintaan dijalankan, waktu saat permintaan diterima, dan nilai resource baru jika permintaan adalah menulis. Header HTTP dan status autentikasi juga disertakan.

Objek request juga berisi ID unik pengguna dan payload Firebase Authentication di objek request.auth , yang akan dijelaskan lebih lanjut di bagian Keamanan Berbasis Pengguna pada dokumen.

Daftar lengkap properti di objek request tersedia di bawah ini:

Properti Jenis Keterangan
auth peta<string, string> Saat pengguna masuk, memberikan uid , ID unik pengguna, dan token , peta klaim Firebase Authentication JWT. Jika tidak, itu akan menjadi null .
params peta<string, string> Peta yang berisi parameter kueri permintaan.
path jalur path yang mewakili jalur tempat permintaan dilakukan.
resource peta<string, string> Nilai sumber daya baru, hanya ada pada permintaan write .
time stempel waktu Stempel waktu yang mewakili waktu server saat permintaan dievaluasi.

Evaluasi Sumber Daya

Saat mengevaluasi aturan, Anda mungkin juga ingin mengevaluasi metadata file yang diunggah, diunduh, dimodifikasi, atau dihapus. Ini memungkinkan Anda untuk membuat aturan yang kompleks dan kuat yang melakukan hal-hal seperti hanya mengizinkan file dengan tipe konten tertentu untuk diunggah, atau hanya file yang lebih besar dari ukuran tertentu yang akan dihapus.

Aturan Keamanan Firebase untuk Cloud Storage menyediakan metadata file di objek resource , yang berisi pasangan kunci/nilai metadata yang muncul di objek Cloud Storage. Properti ini dapat diperiksa pada permintaan read atau write untuk memastikan integritas data.

Pada permintaan write (seperti unggahan, pembaruan metadata, dan penghapusan), selain objek resource , yang berisi metadata file untuk file yang saat ini ada di jalur permintaan, Anda juga memiliki kemampuan untuk menggunakan objek request.resource , yang berisi subset dari metadata file yang akan ditulis jika penulisan diizinkan. Anda dapat menggunakan dua nilai ini untuk memastikan integritas data atau menerapkan batasan aplikasi seperti jenis atau ukuran file.

Daftar lengkap properti di objek resource tersedia di bawah ini:

Properti Jenis Keterangan
name rangkaian Nama lengkap objek
bucket rangkaian Nama ember tempat objek ini berada.
generation ke dalam Pembuatan objek Google Cloud Storage dari objek ini.
metageneration ke dalam Metagenerasi objek Google Cloud Storage dari objek ini.
size ke dalam Ukuran objek dalam byte.
timeCreated stempel waktu Stempel waktu yang menunjukkan waktu suatu objek dibuat.
updated stempel waktu Stempel waktu yang menunjukkan waktu terakhir objek diperbarui.
md5Hash rangkaian Sebuah MD5 hash dari objek.
crc32c rangkaian Sebuah hash crc32c dari objek.
etag rangkaian Etag yang terkait dengan objek ini.
contentDisposition rangkaian Disposisi konten yang terkait dengan objek ini.
contentEncoding rangkaian Encoding konten yang terkait dengan objek ini.
contentLanguage rangkaian Bahasa konten yang terkait dengan objek ini.
contentType rangkaian Jenis konten yang terkait dengan objek ini.
metadata peta<string, string> Pasangan kunci/nilai metadata khusus tambahan yang ditentukan pengembang.

request.resource berisi semua ini dengan pengecualian generation , metageneration , etag , timeCreated , dan updated .

Validasi data

Aturan Keamanan Firebase untuk Cloud Storage juga dapat digunakan untuk validasi data, termasuk memvalidasi nama dan jalur file serta properti metadata file seperti contentType dan size .

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      // Only allow uploads of any image file that's less than 5MB
      allow write: if request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

Fungsi kustom

Saat Aturan Keamanan Firebase menjadi lebih kompleks, Anda mungkin ingin menggabungkan kumpulan kondisi dalam fungsi yang dapat digunakan kembali di seluruh kumpulan aturan. Aturan keamanan mendukung fungsi kustom. Sintaks untuk fungsi khusus agak mirip JavaScript, tetapi fungsi Aturan Keamanan Firebase ditulis dalam bahasa khusus domain yang memiliki beberapa batasan penting:

  • Fungsi hanya dapat berisi satu pernyataan return . Mereka tidak dapat berisi logika tambahan. Misalnya, mereka tidak dapat menjalankan loop atau memanggil layanan eksternal.
  • Fungsi dapat secara otomatis mengakses fungsi dan variabel dari lingkup di mana mereka didefinisikan. Misalnya, fungsi yang ditentukan dalam cakupan service firebase.storage memiliki akses ke variabel resource , dan hanya untuk Cloud Firestore, fungsi bawaan seperti get() dan exists() .
  • Fungsi dapat memanggil fungsi lain tetapi mungkin tidak berulang. Total kedalaman tumpukan panggilan dibatasi hingga 10.
  • Dalam versi rules2 , fungsi dapat mendefinisikan variabel menggunakan kata kunci let . Fungsi dapat memiliki sejumlah let binding, tetapi harus diakhiri dengan pernyataan return.

Sebuah fungsi didefinisikan dengan kata kunci function dan mengambil nol atau lebih argumen. Misalnya, Anda mungkin ingin menggabungkan dua jenis kondisi yang digunakan dalam contoh di atas menjadi satu fungsi:

service firebase.storage {
  match /b/{bucket}/o {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }
    match /images/{imageId} {
      allow read, write: if signedInOrPublic();
    }
    match /mp3s/{mp3Ids} {
      allow read: if signedInOrPublic();
    }
  }
}

Menggunakan fungsi dalam Aturan Keamanan Firebase membuatnya lebih mudah dipelihara seiring dengan bertambahnya kompleksitas aturan Anda.

Langkah selanjutnya

Setelah diskusi tentang kondisi ini, Anda memiliki pemahaman Aturan yang lebih canggih dan siap untuk:

Pelajari cara menangani kasus penggunaan inti, dan pelajari alur kerja untuk mengembangkan, menguji, dan menerapkan Aturan:

,

Panduan ini dibuat berdasarkan mempelajari sintaks inti dari panduan bahasa Aturan Keamanan Firebase untuk menunjukkan cara menambahkan ketentuan ke Aturan Keamanan Firebase untuk Cloud Storage.

Blok penyusun utama Aturan Keamanan Cloud Storage adalah kondisinya . Kondisi adalah ekspresi boolean yang menentukan apakah operasi tertentu harus diizinkan atau ditolak. Untuk aturan dasar, menggunakan literal true dan false sebagai kondisi bekerja dengan sangat baik. Tetapi bahasa Aturan Keamanan Firebase untuk Cloud Storage memberi Anda cara untuk menulis kondisi yang lebih kompleks yang dapat:

  • Periksa otentikasi pengguna
  • Validasi data yang masuk

Autentikasi

Aturan Keamanan Firebase untuk Cloud Storage terintegrasi dengan Firebase Authentication untuk menyediakan autentikasi berbasis pengguna yang andal ke Cloud Storage. Hal ini memungkinkan kontrol akses granular berdasarkan klaim token Firebase Authentication.

Saat pengguna yang diautentikasi melakukan permintaan terhadap Cloud Storage, variabel request.auth diisi dengan uid pengguna ( request.auth.uid ) serta klaim Firebase Authentication JWT ( request.auth.token ).

Selain itu, saat menggunakan autentikasi khusus, klaim tambahan akan muncul di bidang request.auth.token .

Saat pengguna yang tidak diautentikasi melakukan permintaan, variabel request.auth adalah null .

Dengan menggunakan data ini, ada beberapa cara umum untuk menggunakan otentikasi untuk mengamankan file:

  • Publik: abaikan request.auth
  • Pribadi yang diautentikasi: periksa apakah request.auth bukan null
  • Pribadi pengguna: periksa apakah request.auth.uid sama dengan path uid
  • Pribadi grup: periksa klaim token khusus untuk mencocokkan klaim yang dipilih, atau baca metadata file untuk melihat apakah ada bidang metadata

Publik

Aturan apa pun yang tidak mempertimbangkan konteks request.auth dapat dianggap sebagai aturan public , karena tidak mempertimbangkan konteks otentikasi pengguna. Aturan ini dapat berguna untuk menampilkan data publik seperti aset game, file suara, atau konten statis lainnya.

// Anyone to read a public image if the file is less than 100kB
// Anyone can upload a public file ending in '.txt'
match /public/{imageId} {
  allow read: if resource.size < 100 * 1024;
  allow write: if imageId.matches(".*\\.txt");
}

Pribadi yang diautentikasi

Dalam kasus tertentu, Anda mungkin ingin data dapat dilihat oleh semua pengguna aplikasi yang diautentikasi, tetapi tidak oleh pengguna yang tidak diautentikasi. Karena variabel request.auth adalah null untuk semua pengguna yang tidak diautentikasi, yang harus Anda lakukan adalah memeriksa apakah variabel request.auth ada untuk meminta otentikasi:

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

Pribadi pengguna

Sejauh ini, kasus penggunaan yang paling umum untuk request.auth adalah memberikan izin terperinci kepada pengguna individu pada file mereka: mulai dari mengunggah gambar profil hingga membaca dokumen pribadi.

Karena file di Cloud Storage memiliki "jalur" lengkap ke file tersebut, yang diperlukan untuk membuat file yang dikendalikan oleh pengguna adalah bagian dari informasi pengenal pengguna yang unik di awalan nama file (seperti uid pengguna) yang dapat diperiksa ketika aturan dievaluasi:

// Only a user can upload their profile picture, but anyone can view it
match /users/{userId}/profilePicture.png {
  allow read;
  allow write: if request.auth.uid == userId;
}

Grup pribadi

Kasus penggunaan lain yang sama-sama umum adalah untuk mengizinkan izin grup pada suatu objek, seperti mengizinkan beberapa anggota tim untuk berkolaborasi pada dokumen bersama. Ada beberapa pendekatan untuk melakukan ini:

  • Buat token kustom Firebase Authentication yang berisi informasi tambahan tentang anggota grup (seperti ID grup)
  • Sertakan informasi grup (seperti ID grup atau daftar uid resmi) dalam metadata file

Setelah data ini disimpan dalam token atau metadata file, data ini dapat dirujuk dari dalam aturan:

// Allow reads if the group ID in your token matches the file metadata's `owner` property
// Allow writes if the group ID is in the user's custom token
match /files/{groupId}/{fileName} {
  allow read: if resource.metadata.owner == request.auth.token.groupId;
  allow write: if request.auth.token.groupId == groupId;
}

Permintaan Evaluasi

Upload, download, perubahan metadata, dan penghapusan dievaluasi menggunakan request yang dikirim ke Cloud Storage. Selain ID unik pengguna dan payload Firebase Authentication di objek request.auth seperti dijelaskan di atas, variabel request berisi jalur file tempat permintaan dijalankan, waktu saat permintaan diterima, dan nilai resource baru jika permintaan adalah menulis. Header HTTP dan status autentikasi juga disertakan.

Objek request juga berisi ID unik pengguna dan payload Firebase Authentication di objek request.auth , yang akan dijelaskan lebih lanjut di bagian Keamanan Berbasis Pengguna pada dokumen.

Daftar lengkap properti di objek request tersedia di bawah ini:

Properti Jenis Keterangan
auth peta<string, string> Saat pengguna masuk, memberikan uid , ID unik pengguna, dan token , peta klaim Firebase Authentication JWT. Jika tidak, itu akan menjadi null .
params peta<string, string> Peta yang berisi parameter kueri permintaan.
path jalur path yang mewakili jalur tempat permintaan dilakukan.
resource peta<string, string> Nilai sumber daya baru, hanya ada pada permintaan write .
time stempel waktu Stempel waktu yang mewakili waktu server saat permintaan dievaluasi.

Evaluasi Sumber Daya

Saat mengevaluasi aturan, Anda mungkin juga ingin mengevaluasi metadata file yang diunggah, diunduh, dimodifikasi, atau dihapus. Ini memungkinkan Anda untuk membuat aturan yang kompleks dan kuat yang melakukan hal-hal seperti hanya mengizinkan file dengan tipe konten tertentu untuk diunggah, atau hanya file yang lebih besar dari ukuran tertentu yang akan dihapus.

Aturan Keamanan Firebase untuk Cloud Storage menyediakan metadata file di objek resource , yang berisi pasangan kunci/nilai metadata yang muncul di objek Cloud Storage. Properti ini dapat diperiksa pada permintaan read atau write untuk memastikan integritas data.

Pada permintaan write (seperti unggahan, pembaruan metadata, dan penghapusan), selain objek resource , yang berisi metadata file untuk file yang saat ini ada di jalur permintaan, Anda juga memiliki kemampuan untuk menggunakan objek request.resource , yang berisi subset dari metadata file yang akan ditulis jika penulisan diizinkan. Anda dapat menggunakan dua nilai ini untuk memastikan integritas data atau menerapkan batasan aplikasi seperti jenis atau ukuran file.

Daftar lengkap properti di objek resource tersedia di bawah ini:

Properti Jenis Keterangan
name rangkaian Nama lengkap objek
bucket rangkaian Nama ember tempat objek ini berada.
generation ke dalam Pembuatan objek Google Cloud Storage dari objek ini.
metageneration ke dalam Metagenerasi objek Google Cloud Storage dari objek ini.
size ke dalam Ukuran objek dalam byte.
timeCreated stempel waktu Stempel waktu yang menunjukkan waktu suatu objek dibuat.
updated stempel waktu Stempel waktu yang menunjukkan waktu terakhir objek diperbarui.
md5Hash rangkaian Sebuah MD5 hash dari objek.
crc32c rangkaian Sebuah hash crc32c dari objek.
etag rangkaian Etag yang terkait dengan objek ini.
contentDisposition rangkaian Disposisi konten yang terkait dengan objek ini.
contentEncoding rangkaian Encoding konten yang terkait dengan objek ini.
contentLanguage rangkaian Bahasa konten yang terkait dengan objek ini.
contentType rangkaian Jenis konten yang terkait dengan objek ini.
metadata peta<string, string> Pasangan kunci/nilai metadata khusus tambahan yang ditentukan pengembang.

request.resource berisi semua ini dengan pengecualian generation , metageneration , etag , timeCreated , dan updated .

Validasi data

Aturan Keamanan Firebase untuk Cloud Storage juga dapat digunakan untuk validasi data, termasuk memvalidasi nama dan jalur file serta properti metadata file seperti contentType dan size .

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      // Only allow uploads of any image file that's less than 5MB
      allow write: if request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

Fungsi kustom

Saat Aturan Keamanan Firebase menjadi lebih kompleks, Anda mungkin ingin menggabungkan kumpulan kondisi dalam fungsi yang dapat digunakan kembali di seluruh kumpulan aturan. Aturan keamanan mendukung fungsi kustom. Sintaks untuk fungsi khusus agak mirip JavaScript, tetapi fungsi Aturan Keamanan Firebase ditulis dalam bahasa khusus domain yang memiliki beberapa batasan penting:

  • Fungsi hanya dapat berisi satu pernyataan return . Mereka tidak dapat berisi logika tambahan. Misalnya, mereka tidak dapat menjalankan loop atau memanggil layanan eksternal.
  • Fungsi dapat secara otomatis mengakses fungsi dan variabel dari lingkup di mana mereka didefinisikan. Misalnya, fungsi yang ditentukan dalam cakupan service firebase.storage memiliki akses ke variabel resource , dan hanya untuk Cloud Firestore, fungsi bawaan seperti get() dan exists() .
  • Fungsi dapat memanggil fungsi lain tetapi mungkin tidak berulang. Total kedalaman tumpukan panggilan dibatasi hingga 10.
  • Dalam versi rules2 , fungsi dapat mendefinisikan variabel menggunakan kata kunci let . Fungsi dapat memiliki sejumlah let binding, tetapi harus diakhiri dengan pernyataan return.

Sebuah fungsi didefinisikan dengan kata kunci function dan mengambil nol atau lebih argumen. Misalnya, Anda mungkin ingin menggabungkan dua jenis kondisi yang digunakan dalam contoh di atas menjadi satu fungsi:

service firebase.storage {
  match /b/{bucket}/o {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }
    match /images/{imageId} {
      allow read, write: if signedInOrPublic();
    }
    match /mp3s/{mp3Ids} {
      allow read: if signedInOrPublic();
    }
  }
}

Menggunakan fungsi dalam Aturan Keamanan Firebase membuatnya lebih mudah dipelihara seiring dengan bertambahnya kompleksitas aturan Anda.

Langkah selanjutnya

Setelah diskusi tentang kondisi ini, Anda memiliki pemahaman Aturan yang lebih canggih dan siap untuk:

Pelajari cara menangani kasus penggunaan inti, dan pelajari alur kerja untuk mengembangkan, menguji, dan menerapkan Aturan: