آلية عمل "قواعد الأمان"

Cloud Firestore

البنية الأساسية

Firebase Security Rules في Cloud Firestore وCloud Storage تستخدم البنية و بناء الجملة:

service <<name>> {
  // Match the resource path.
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}

من المهم فهم المفاهيم الأساسية التالية أثناء وضع القواعد:

• الطلب: الطريقة أو الطرق التي تم استدعاؤها في عبارة allow. وهي الطرق التي تسمح بتشغيلها. الطرق العادية هي: get وlist create وupdate وdelete الطريقتان read وwrite الملائمتان تمكين الوصول الواسع للقراءة والكتابة في قاعدة البيانات أو مسار التخزين المحدد.
• المسار: قاعدة البيانات أو موقع التخزين، ويتم تمثيله على شكل مسار معرّف الموارد المنتظم (URI).
• القاعدة: عبارة allow، التي تتضمن شرطًا يسمح إذا تم تقييمه على true.

الإصدار 2 من قواعد الأمان

اعتبارًا من أيار (مايو) 2019، أصبح الإصدار 2 من قواعد الأمان من Firebase متاحًا الآن. المتوفرة. يغيّر الإصدار 2 من القواعد سلوك التكراري أحرف البدل {name=**} عليك استخدام الإصدار 2 إذا كنت تخطّط استخدام طلبات بحث مجموعات المجموعات. يجب الموافقة على الإصدار 2 من خلال جعل rules_version = '2'; السطر الأول ضِمن إعدادات الأمان القواعد:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

المسارات المطابقة

يجب أن تشير كل عبارات المطابقة إلى المستندات، وليس إلى المجموعات. مطابقة يمكن أن تشير العبارة إلى مستند معيّن، كما في match /cities/SF أو استخدام أحرف البدل للإشارة إلى أي مستند في المسار المحدد، كما في match /cities/{city}.

في المثال أعلاه، تستخدِم عبارة المطابقة بنية حرف البدل {city}. وهذا يعني أن القاعدة تنطبق على أي مستند في مجموعة cities، مثل /cities/SF أو /cities/NYC. عندما تكون تعبيرات allow في عبارة المطابقة سيتم تحليل المتغير city مع اسم مستند المدينة، مثل SF أو NYC.

مطابقة المجموعات الفرعية

يتم تنظيم البيانات في "Cloud Firestore" في مجموعات من المستندات، الوثيقة بتوسيع التسلسل الهرمي من خلال المجموعات الفرعية. من المهم فهم كيفية تفاعل قواعد الأمان مع البيانات الهرمية.

يُرجى مراعاة أنّ كل مستند في مجموعة cities يحتوي على مجموعة فرعية واحدة (landmarks) لا تنطبق قواعد الأمان إلا على المسار المطابق، ولذلك عناصر التحكّم في الوصول المحدّدة في مجموعة cities لا تنطبق على مجموعة فرعية واحدة (landmarks) بدلاً من ذلك، يمكنك كتابة قواعد صريحة للتحكم في الوصول إلى البيانات إلى المجموعات الفرعية:

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      allow read, write: if <condition>;

      // Explicitly define rules for the 'landmarks' subcollection
      match /landmarks/{landmark} {
        allow read, write: if <condition>;
      }
    }
  }
}

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

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      match /landmarks/{landmark} {
        allow read, write: if <condition>;
      }
    }
  }
}

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city}/landmarks/{landmark} {
      allow read, write: if <condition>;
    }
  }
}

أحرف البدل المتكررة

إذا أردت تطبيق القواعد على تسلسل هرمي عميق عشوائيًا، فاستخدم بنية حرف بدل متكررة، {name=**}:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

عند استخدام بناء جملة حرف البدل التكراري، سيحتوي متغير حرف البدل على مقطع مسار مطابقة بأكمله، حتى إذا كان المستند موجودًا في جزء متداخل بشدة للمجموعة الفرعية. على سبيل المثال، ستتطابق القواعد الواردة أعلاه مع مستند موجود على /cities/SF/landmarks/coit_tower، وقيمة فسيكون المتغير document هو SF/landmarks/coit_tower.

لكن لاحظ أن سلوك أحرف البدل المتكررة يعتمد على القواعد .

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{city}/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the songs collection group
    match /{path=**}/songs/{song} {
      allow read, write: if <condition>;
    }
  }
}

إذا كنت تستخدم طلبات بحث لمجموعة المختارات، يجب استخدام 2، راجِع تأمين طلبات بحث مجموعات المجموعات.

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

من الممكن أن يتطابق مستند مع أكثر من عبارة match واحدة. في جلسة المعمل، الحالة التي تتطابق فيها تعبيرات allow متعدّدة مع طلب، يتم السماح بالوصول إذا كان أي من الشروط هو true:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the 'cities' collection.
    match /cities/{city} {
      allow read, write: if false;
    }

    // Matches any document in the 'cities' collection or subcollections.
    match /cities/{document=**} {
      allow read, write: if true;
    }
  }
}

في المثال أعلاه، ستكون كل عمليات القراءة والكتابة في المجموعة cities كما هي مسموح بها لأن القاعدة الثانية هي دائمًا true، على الرغم من أن القاعدة الأولى هي false دائمًا.

حدود قواعد الأمان

عند العمل مع قواعد الأمان، لاحِظ الحدود التالية:

Cloud Storage

البنية الأساسية

Firebase Security Rules في Cloud Firestore وCloud Storage تستخدم البنية و بناء الجملة:

service <<name>> {
  // Match the resource path.
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}

من المهم فهم المفاهيم الأساسية التالية أثناء وضع القواعد:

• الطلب: الطريقة أو الطرق التي تم استدعاؤها في عبارة allow. وهي الطرق التي تسمح بتشغيلها. الطرق العادية هي: get وlist create وupdate وdelete الطريقتان read وwrite الملائمتان تمكين الوصول الواسع للقراءة والكتابة في قاعدة البيانات أو مسار التخزين المحدد.
• المسار: قاعدة البيانات أو موقع التخزين، ويتم تمثيله على شكل مسار معرّف الموارد المنتظم (URI).
• القاعدة: عبارة allow، التي تتضمن شرطًا يسمح إذا تم تقييمه على true.

المسارات المطابقة

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

النتائج المتطابقة تمامًا

// Exact match for "images/profilePhoto.png"
match /images/profilePhoto.png {
  allow write: if <condition>;
}

// Exact match for "images/croppedProfilePhoto.png"
match /images/croppedProfilePhoto.png {
  allow write: if <other_condition>;
}

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

// Partial match for files that start with "images"
match /images {
  // Exact match for "images/profilePhoto.png"
  match /profilePhoto.png {
    allow write: if <condition>;
  }

  // Exact match for "images/croppedProfilePhoto.png"
  match /croppedProfilePhoto.png {
    allow write: if <other_condition>;
  }
}

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

يمكن أيضًا استخدام القواعد بهدف match نمط باستخدام أحرف البدل. حرف البدل هو متغير مُسمى يمثل إما سلسلة واحدة مثل profilePhoto.png أو شرائح مسار متعددة، مثل images/profilePhoto.png

يتم إنشاء حرف بدل عن طريق إضافة أقواس متعرجة حول اسم حرف البدل، مثل {string} يمكن الإعلان عن حرف بدل متعدد الشرائح عن طريق إضافة =** إلى اسم حرف بدل، مثل {path=**}:

// Partial match for files that start with "images"
match /images {
  // Exact match for "images/*"
  // e.g. images/profilePhoto.png is matched
  match /{imageId} {
    // This rule only matches a single path segment (*)
    // imageId is a string that contains the specific segment matched
    allow read: if <condition>;
  }

  // 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

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

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

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

طلب تقييم

يتم تقييم عمليات التحميل وعمليات التنزيل وتغييرات البيانات الوصفية وعمليات الحذف باستخدام تم إرسال مبلغ request إلى "Cloud Storage". يحتوي المتغير request على مسار الملف الذي يتم فيه تنفيذ الطلب، ووقت تنفيذ الطلب والقيمة resource الجديدة إذا كان الطلب كتابة. عناوين HTTP بالإضافة إلى حالة المصادقة.

يحتوي كائن request أيضًا على المعرّف الفريد للمستخدم حمولة Firebase Authentication في الكائن request.auth، والتي سيتم أوضحنا بالتفصيل في قسم المصادقة قسم المستندات.

في ما يلي قائمة كاملة بالسمات في الكائن request:

تقييم الموارد

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

يوفّر Firebase Security Rules للنطاق Cloud Storage البيانات الوصفية للملفات في resource. يحتوي على أزواج المفتاح/القيمة من البيانات الوصفية التي تظهر في كائن Cloud Storage. يمكن فحص هذه السمات على read أو هناك طلبان (write) لضمان سلامة البيانات.

في طلبات write (مثل عمليات التحميل وتعديل البيانات الوصفية وعمليات الحذف)، في بالإضافة إلى الكائن resource الذي يتضمن البيانات الوصفية للملف التي توجد حاليًا في مسار الطلب، يمكنك أيضًا استخدام request.resource، الذي يحتوي على مجموعة فرعية من البيانات الوصفية للملف إذا كانت الكتابة مسموحًا بها. يمكنك استخدام هاتين القيمتين لضمان التكامل أو فرض قيود على التطبيق مثل نوع الملف أو حجمه.

في ما يلي قائمة كاملة بالسمات في الكائن resource:

يحتوي request.resource على كل ما يلي باستثناء generation، metageneration وetag وtimeCreated وupdated

حدود قواعد الأمان

عند العمل مع قواعد الأمان، لاحِظ الحدود التالية:

مثال كامل

بوضع كل شيء معًا، يمكنك إنشاء مثال كامل لقواعد إحدى الصور حل التخزين:

service firebase.storage {
 match /b/{bucket}/o {
   match /images {
     // Cascade read to any image type at any path
     match /{allImages=**} {
       allow read;
     }

     // Allow write files to the path "images/*", subject to the constraints:
     // 1) File is less than 5MB
     // 2) Content type is an image
     // 3) Uploaded content type matches existing content type
     // 4) File name (stored in imageId wildcard variable) is less than 32 characters
     match /{imageId} {
       allow write: if request.resource.size < 5 * 1024 * 1024
                    && request.resource.contentType.matches('image/.*')
                    && request.resource.contentType == resource.contentType
                    && imageId.size() < 32
     }
   }
 }
}

Realtime Database

البنية الأساسية

في Realtime Database، يتكون Firebase Security Rules من تعبيرات تشبه JavaScript مضمنة في مستند JSON.

يستخدم بناء الجملة التالي:

{
  "rules": {
    "<<path>>": {
    // Allow the request if the condition for each method is true.
      ".read": <<condition>>,
      ".write": <<condition>>,
      ".validate": <<condition>>
    }
  }
}

تتضمّن القاعدة ثلاثة عناصر أساسية:

• المسار: موقع قاعدة البيانات. يعكس هذا بنية JSON لقاعدة بياناتك.
• الطلب: هذه هي الطرق التي تستخدمها القاعدة لمنح إذن الوصول. read وتمنح قواعد write إذنًا واسعًا للقراءة والكتابة، بينما تمنح قواعد validate بمثابة إثبات ثانوي لمنح إذن الوصول استنادًا إلى الأذونات الواردة أو الحالية البيانات.
• الحالة: وهي الحالة التي تسمح بتقديم طلب إذا تم تقييمه على أنّه صحيح.

كيفية تطبيق القواعد على المسارات

في Realtime Database، تُطبَّق Rules بشكلٍ كامل، ما يعني أن القواعد في تلغي العُقد الرئيسية ذات المستوى الأعلى القواعد في العُقد الفرعية الأكثر دقة لا يمكن أن تمنح القواعد الموجودة في أي نقطة أعمق إمكانية الوصول إلى مسار رئيسي. إِنْتَ لا يمكنك تحسين الوصول أو إبطاله في مسار أعمق في بنية قاعدة البيانات إذا وقد منحته من قبل لأحد المسارات الرئيسية.

يُرجى مراعاة القواعد التالية:

{
  "rules": {
     "foo": {
        // allows read to /foo/*
        ".read": "data.child('baz').val() === true",
        "bar": {
          // ignored, since read was allowed already
          ".read": false
        }
     }
  }
}

تتيح بنية الأمان هذه إمكانية قراءة "/bar/" من أي وقت. يحتوي /foo/ على عنصر baz فرعي بقيمة true. لا تحتوي قاعدة ".read": false ضمن /foo/bar/ على تأثير هنا، حيث لا يمكن إبطال الدخول عن طريق مسار فرعي.

ورغم أن الأمر قد لا يبدو بديهيًا على الفور، إلا أن هذا يعد جزءًا قويًا من قواعد اللغة ويسمح بتنفيذ امتيازات الوصول المعقدة للغاية بأقل جهد. وهذا مفيد بشكل خاص لأغراض الأمان المستندة إلى المستخدم.

يُرجى العِلم أنّ قواعد .validate لا تتتالي. جميع قواعد التحقق من الصحة يجب أن يكون راضيًا على جميع مستويات التسلسل الهرمي حتى يتم السماح بالكتابة.

بالإضافة إلى ذلك، لا تنطبق القواعد مرة أخرى على المسار الرئيسي، ما يعني أنّ ميزة القراءة أو الكتابة تفشل العملية إذا لم تكن هناك قاعدة في الموقع المطلوب أو في أحد الوالدين الموقع الذي يمنح حق الوصول. حتى إذا كان من الممكن الوصول إلى كل مسار فرعي متأثر، ستفشل القراءة في الموقع الأصلي تمامًا. ضع في اعتبارك هذا الهيكل:

{
  "rules": {
    "records": {
      "rec1": {
        ".read": true
      },
      "rec2": {
        ".read": false
      }
    }
  }
}

بدون فهم أن القواعد يتم تقييمها على نحو ذري، قد يبدو الأمر مثل أن استرجاع مسار /records/ سيؤدي إلى عرض rec1 ولكن ليس rec2. ومع ذلك، فإن النتيجة الفعلية هي خطأ:

var db = firebase.database();
db.ref("records").once("value", function(snap) {
  // success method is not called
}, function(err) {
  // error callback triggered with PERMISSION_DENIED
});

FIRDatabaseReference *ref = [[FIRDatabase database] reference];
[[_ref child:@"records"] observeSingleEventOfType:FIRDataEventTypeValue withBlock:^(FIRDataSnapshot *snapshot) {
  // success block is not called
} withCancelBlock:^(NSError * _Nonnull error) {
  // cancel block triggered with PERMISSION_DENIED
}];

var ref = FIRDatabase.database().reference()
ref.child("records").observeSingleEventOfType(.Value, withBlock: { snapshot in
    // success block is not called
}, withCancelBlock: { error in
    // cancel block triggered with PERMISSION_DENIED
})

FirebaseDatabase database = FirebaseDatabase.getInstance();
DatabaseReference ref = database.getReference("records");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
  @Override
  public void onDataChange(DataSnapshot snapshot) {
    // success method is not called
  }

  @Override
  public void onCancelled(FirebaseError firebaseError) {
    // error callback triggered with PERMISSION_DENIED
  });
});

curl https://docs-examples.firebaseio.com/rest/records/
# response returns a PERMISSION_DENIED error

بما أنّ عملية القراءة في /records/ شاملة، ولا تتوفّر قاعدة قراءة تتيح الوصول إلى جميع البيانات ضمن /records/، سيؤدي ذلك إلى ظهور خطأ PERMISSION_DENIED. إذا قيّمنا هذه القاعدة في مُحاكي الأمان ضمن وحدة تحكُّم Firebase، يتضّح لنا أنّه تم رفض عملية القراءة:

Attempt to read /records with auth=Success(null)
    /
    /records

No .read rule allowed the operation.
Read was denied.

تم رفض العملية بسبب عدم سماح أي قاعدة قراءة بالوصول إلى مسار /records/، ولكن تجدر الإشارة إلى أنّه لم يتم تقييم قاعدة rec1 مطلقًا لأنّها لم تكن في المسار الذي طلبناه. لجلب rec1، يجب الوصول إليه مباشرةً:

var db = firebase.database();
db.ref("records/rec1").once("value", function(snap) {
  // SUCCESS!
}, function(err) {
  // error callback is not called
});

FIRDatabaseReference *ref = [[FIRDatabase database] reference];
[[ref child:@"records/rec1"] observeSingleEventOfType:FEventTypeValue withBlock:^(FIRDataSnapshot *snapshot) {
    // SUCCESS!
}];

var ref = FIRDatabase.database().reference()
ref.child("records/rec1").observeSingleEventOfType(.Value, withBlock: { snapshot in
    // SUCCESS!
})

FirebaseDatabase database = FirebaseDatabase.getInstance();
DatabaseReference ref = database.getReference("records/rec1");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
  @Override
  public void onDataChange(DataSnapshot snapshot) {
    // SUCCESS!
  }

  @Override
  public void onCancelled(FirebaseError firebaseError) {
    // error callback is not called
  }
});

curl https://docs-examples.firebaseio.com/rest/records/rec1
# SUCCESS!

متغيّر الموقع الجغرافي

Realtime Database Rules تدعم $location متغير لمطابقة مقاطع المسار. استخدِم البادئة $ قبل مسارك. تقسيم الصفحة لمطابقة القاعدة مع أي عُقد فرعية على طول المسار.

  {
    "rules": {
      "rooms": {
        // This rule applies to any child of /rooms/, the key for each room id
        // is stored inside $room_id variable for reference
        "$room_id": {
          "topic": {
            // The room's topic can be changed if the room id has "public" in it
            ".write": "$room_id.contains('public')"
          }
        }
      }
    }
  }

يمكنك أيضًا استخدام $variable بالتوازي مع المسار الثابت. الأسماء.

  {
    "rules": {
      "widget": {
        // a widget can have a title or color attribute
        "title": { ".validate": true },
        "color": { ".validate": true },

        // but no other child paths are allowed
        // in this case, $other means any key excluding "title" and "color"
        "$other": { ".validate": false }
      }
    }
  }