التعرُّف على البنية الأساسية لقواعد أمان Firebase للغة Cloud Storage

يسمح لك تطبيق Firebase Security Rules لـ Cloud Storage بالتحكّم في الوصول إلى العناصر المخزَّنة. في Cloud Storage مجموعة بيانات تسمح لك بنية القواعد المرنة بإنشاء للتحكّم في أي عملية، بدءًا من جميع عمليات الكتابة إلى Cloud Storage إلى العمليات على ملف معين.

ملاحظة: تحتوي المجموعات في Cloud Storage على ملفات فقط ولا تحتوي على الأخرى. في هذه الصفحة، سترى الشرطات المائلة / في أسماء الملفات، مثل /images/profilePhoto.png، مما يشير إلى وجود تسلسل هرمي للأدلة والدلائل الفرعية في إحدى الحزم ومع ذلك، يمكن أن تتضمن أسماء الملفات بادئات ذات الشرطات المائلة للسماح لك بتحديد أسماء ملفات فريدة تشبه مسارات الدليل التي اعتدنا رؤيتها في أنظمة الملفات.

يصف هذا الدليل البنية الأساسية لدالة Cloud Storage Security Rules وبنيتها وإنشاء مجموعات قواعد كاملة.

بيان الخدمة وقاعدة البيانات

دائمًا ما تبدأ الدالة Firebase Security Rules لـ Cloud Storage بالبيان التالي:

service firebase.storage {
    // ...
}

يحدّد بيان service firebase.storage القواعد Cloud Storage، ما يؤدي إلى منع التعارضات بين Cloud Storage Security Rules و وقواعد لمنتجات أخرى مثل Cloud Firestore.

قواعد القراءة/الكتابة الأساسية

تتكون القواعد الأساسية من عبارة match تحدد Cloud Storage وهي عبارة عن عبارة مطابقة تحدد اسم ملف وتعبير allow يُسمح بالتفاصيل عند قراءة البيانات المحددة. allow تعبيرات تحديد طرق الوصول (مثل القراءة والكتابة) والشروط يتم بموجبه السماح بالوصول أو رفضه.

في مجموعة القواعد التلقائية، تستخدم عبارة match الأولى حرف بدل {bucket}. للإشارة إلى أن القواعد تنطبق على جميع المجموعات في مشروعك. سنضيف سنناقش فكرة تطابق حرف البدل بشكل أكبر في القسم التالي.

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

تشير جميع عبارات المطابقة إلى الملفات. يمكن أن تشير عبارة المطابقة إلى عبارة معينة ملف، كما في match /images/profilePhoto.png.

مطابقة أحرف البدل

بالإضافة إلى الإشارة إلى ملف واحد، يمكن لـ Rules استخدام أحرف البدل للإشارة إلى أي ملف يحتوي على بادئة سلسلة معينة في اسمه، بما في ذلك الشرطات المائلة، كما في match /images/{imageId}.

في المثال أعلاه، تستخدِم عبارة المطابقة بنية حرف البدل {imageId}. وهذا يعني أن القاعدة تنطبق على أي ملف يحتوي على الاسم /images/ في بداية اسمه، مثل /images/profilePhoto.png أو /images/croppedProfilePhoto.png. عندما يتم تقييم تعبيرات allow في عبارة المطابقة، وهو المتغير imageId ستتم مطابقته إلى اسم ملف الصورة، مثل profilePhoto.png أو croppedProfilePhoto.png

يمكن الإشارة إلى متغيّر حرف بدل من داخل match لتقديم ملف تفويض الاسم أو المسار:

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

ملاحظة: يمكن للمستخدمين الوصول فقط إلى الملفات التي يسمح بها Firebase Security Rules على وجه التحديد الدخول إليها. على سبيل المثال، تسمح القواعد الموضّحة أعلاه بالوصول إلى الملفات فقط. مع /images/ في بداية أسمائها؛ ونتيجة لذلك، ينكرون أيضًا الوصول إلى الملفات التي تحتوي على بادئات أسماء مختلفة.

البيانات الهرمية

كما ذكرنا من قبل، لا يوجد هيكل هرمي داخل حزمة واحدة (Cloud Storage) ولكن باستخدام اصطلاح تسمية ملفات، غالبًا ما يكون أحد يتضمن شرطات مائلة في أسماء الملفات، يمكننا محاكاة هيكل يبدو سلسلة متداخلة من الدلائل والأدلة الفرعية. من المهم أن تفهم كيفية تفاعل Firebase Security Rules مع أسماء الملفات هذه.

ضع في اعتبارك حالة مجموعة من الملفات التي تبدأ جميعًا بأسماء جذع /images/ ولا تُطبق Firebase Security Rules إلا على اسم الملف المطابق، وبالتالي تُتاح إمكانية الوصول عناصر التحكّم المحددة في النص الأساسي /images/ لا تنطبق على عنصر التحكّم البنيوي /mp3s/. بدلاً من ذلك، يمكنك كتابة قواعد صريحة تتطابق مع أنماط أسماء الملفات المختلفة:

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

عند دمج عبارات match، يكون مسار عبارة match الداخلية هو ملحقة دائمًا بمسار عبارة match الخارجية. ما يلي: وبالتالي، تكون مجموعتا قواعد متساويتين:

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

أحرف البدل ذات المطابقة التكرارية

بالإضافة إلى أحرف البدل التي تتطابق وترجع السلاسل في نهاية اسم الملف، ويمكن الإعلان عن حرف بدل متعدد الأقسام لإجراء مطابقة أكثر تعقيدًا عن طريق إضافة =** إلى اسم حرف البدل، مثل {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>;
  }
}

إذا تطابقت قواعد متعددة مع ملف، تكون النتيجة OR لنتيجة جميع وتقييم القواعد. أي إذا تم تقييم أي قاعدة تطابقها الملف مع true، سيتم النتيجة هي true.

في القواعد أعلاه، يتم ملف "images/profilePhoto.png" يمكن قراءتها إذا يتم تقييم condition أو other_condition على "صحيح"، بينما يتم تقييم الملف "images/users/user:12345/profilePhoto.png" لا تخضع إلا لنتيجة other_condition

لا يتصاعد Cloud Storage Security Rules، ولا يتم تقييم القواعد إلا عند يتطابق مسار الطلب مع مسار بالقواعد المحدّدة.

الإصدار 1

يستخدم Firebase Security Rules الإصدار 1 تلقائيًا. في الإصدار 1، أحرف البدل المتكررة تطابق عنصرًا واحدًا أو أكثر من عناصر اسم الملف، وليس عنصرًا أو أكثر. وبالتالي، تتطابق match /images/{filenamePrefixWildcard}/{imageFilename=**} مع اسم ملف. مثل /images/profilePics/profile.png، ولكن ليس /images/badge.png. استخدام /images/{imagePrefixorFilename=**} بدلاً من ذلك.

يجب أن تأتي أحرف البدل المتكررة في نهاية عبارة المطابقة.

وننصحك باستخدام الإصدار 2 للاستفادة من ميزاته الأكثر فعالية.

الإصدار 2

في الإصدار 2 من Firebase Security Rules، لا تتطابق أحرف البدل المتكررة مع مسار أو أكثر عناصر. وبالتالي، مباريات /images/{filenamePrefixWildcard}/{imageFilename=**} filenames /images/profilePics/profile.png و /images/badge.png.

يجب الموافقة على الإصدار 2 من خلال إضافة rules_version = '2'; في أعلى قواعد الأمان:

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

يمكنك استخدام حرف بدل تكراري واحد على الأكثر لكل عبارة مطابقة، ولكن في 2، يمكنك وضع حرف البدل هذا في أي مكان في عبارة المطابقة. بالنسبة مثال:

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

العمليات الدقيقة

في بعض الحالات، من المفيد تقسيم read وwrite إلى أقسام. العمليات الدقيقة. على سبيل المثال، قد يحتاج تطبيقك إلى فرض قيود الشروط عند إنشاء الملف مقارنة بحذف الملف.

يمكن تقسيم عملية read إلى get وlist.

ملاحظة: list Rules API وبالتالي Cloud Storage List API هي متوفّرة فقط في المشاريع التي تستخدم الإصدار 2 من Rules.

يمكن أن تكون قاعدة write تم تقسيمها إلى create وupdate و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>;
    }
  }
 }
}

تداخل عبارات المطابقة

من الممكن أن يتطابق اسم ملف مع أكثر من عبارة match واحدة. في جلسة المعمل، الحالة التي تتطابق فيها تعبيرات allow متعدّدة مع طلب، يتم السماح بالوصول إذا كان أي من الشروط هو 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;
    }
  }
}

في المثال أعلاه، تتم قراءة الملفات التي تبدأ أسماؤها بـ يُسمح باستخدام /images/ لأن القاعدة الثانية هي دائمًا true، حتى عندما فإن القاعدة الأولى هي false.

القواعد ليست فلاتر

عند تأمين بياناتك والبدء في تنفيذ العمليات على الملفات، تذكّر أن قواعد الأمان ليست فلاتر. لا يمكنك تنفيذ عمليات على مجموعة من ملفان يطابقان نمط اسم ملف ويتوقعان وصول Cloud Storage فقط الملفات التي يمتلك العميل الحالي إذنًا بالوصول إليها.

على سبيل المثال، اتّبِع قاعدة الأمان التالية:

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

مرفوضة: ترفض هذه القاعدة ما يلي الطلب لأن مجموعة النتائج يمكن أن تتضمن ملفات حيث يكون contentType ليس image/png:

الويب

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

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

تعمل القواعد في Cloud Storage Security Rules على تقييم كل طلب بحث مقارنةً بإمكانياته. وإخفاقًا في الطلب إذا كان من الممكن عرض ملف يقوم العميل بعرضه ليس لدي إذن بالقراءة. يجب أن تتبع طلبات الوصول القيود التي تم تعيينها بواسطة قواعدك.

الخطوات التالية

يمكنك تعميق فهمك لـ Firebase Security Rules في Cloud Storage:

• تعرف على المفهوم الرئيسي التالي للغة القواعد، الديناميكية الشروط، التي تسمح لـ "القواعد" بالتحقّق من تفويض المستخدم، ومقارنة البيانات الحالية والواردة والتحقق من صحة البيانات الواردة والمزيد.

• راجِع حالات الاستخدام المعتادة للأمان تعريف Firebase Security Rules يعالجها

يمكنك استكشاف Firebase Security Rules حالات استخدام متعلقة بـ "Cloud Storage":