إدارة قواعد أمان Firebase ونشرها

توفّر لك Firebase عدة أدوات لإدارة Rules، وكل أداة مفيدة في حالات معيّنة، وتستخدم كل أداة واجهة برمجة التطبيقات نفسها الخاصة بإدارة "قواعد الأمان" في Firebase.

بغض النظر عن الأداة المستخدَمة لتفعيلها، فإنّ واجهة برمجة التطبيقات الإدارية:

  • تستوعب مصدر القواعد: مجموعة من القواعد، وعادةً ما يكون ملف تعليمة برمجية يحتوي على عبارات Firebase Security Rules.
  • يخزّن المصدر الذي تمّت إضافته على شكل مجموعة قواعد غير قابلة للتغيير.
  • تتبُّع عملية نشر كل مجموعة قواعد في إصدار تستند الخدمات التي تتيح استخدام "قواعد الأمان" في Firebase إلى البحث عن إصدار مشروع معيّن لتقييم كل طلب خاص بمورد آمن.
  • توفّر إمكانية إجراء اختبارات نحوية ودلالية لمجموعة قواعد.

استخدام واجهة سطر الأوامر (CLI) الخاصة بـ Firebase

باستخدام Firebase CLI، يمكنك تحميل المصادر المحلية ونشر الإصدارات. تتيح لك واجهة سطر الأوامر Firebase Local Emulator Suite إجراء اختبار محلي كامل للمصادر.

يتيح لك استخدام واجهة سطر الأوامر إبقاء قواعدك تحت التحكّم في الإصدارات مع رمز التطبيق ونشر القواعد كجزء من عملية النشر الحالية.

إنشاء ملف إعداد

عند إعداد مشروعك على Firebase باستخدام واجهة سطر الأوامر Firebase، يمكنك إنشاء ملف إعداد .rules في دليل مشروعك. استخدِم الأمر التالي لبدء إعداد مشروعك على Firebase:

Cloud Firestore Realtime Database Cloud Storage 
// Set up Firestore in your project directory, creates a .rules file
firebase init firestore
// Set up Realtime Database in your project directory, creates a .rules file
firebase init database
// Set up Storage in your project directory, creates a .rules file
firebase init storage

تعديل قواعدك وتحديثها

عدِّل مصدر القواعد مباشرةً في ملف الإعداد .rules.

تأكَّد من أنّ أي تعديلات تجريها في واجهة سطر الأوامر Firebase تظهر في وحدة تحكّم Firebase، أو أنّك تجري التعديلات باستمرار باستخدام وحدة تحكّم Firebase أو واجهة سطر الأوامر في Firebase. وفي حال عدم مراعاة ذلك، قد يتم استبدال أي تعديلات تم إجراؤها في وحدة تحكّم Firebase.

اختبار التحديثات

توفّر Local Emulator Suite محاكيات لجميع المنتجات التي تم تفعيل "قواعد الأمان" فيها. يُجري محرّك "قواعد الأمان" لكل محاكي تقييمًا نحويًا ودلاليًا للقواعد، ما يتجاوز الاختبار النحوي الذي توفّره واجهة برمجة التطبيقات لإدارة "قواعد الأمان".

إذا كنت تعمل باستخدام واجهة سطر الأوامر، فإنّ Suite هي أداة ممتازة Firebase Security Rulesلإجراء الاختبارات. استخدِم Local Emulator Suite لاختبار التحديثات على جهازك والتأكّد من أنّ Rules في تطبيقك تتوافق مع السلوك الذي تريده.

نشر التحديثات

بعد تعديل Rules واختباره، يمكنك نشر المصادر في بيئة الإنتاج.

بالنسبة إلى Cloud Firestore Security Rules، اربط ملفات .rules بقواعد البيانات التلقائية وقواعد البيانات الإضافية التي تحمل أسماءً من خلال مراجعة ملف firebase.json وتعديله.

استخدِم الأوامر التالية لنشر Rules بشكل انتقائي وحده أو كجزء من عملية النشر العادية.

Cloud Firestore Realtime Database Cloud Storage 
// Deploy rules for all databases configured in your firebase.json
firebase deploy --only firestore:rules

// Deploy rules for the specified database configured in your firebase.json
firebase deploy --only firestore:<databaseId>
// Deploy your .rules file
firebase deploy --only database
// Deploy your .rules file
firebase deploy --only storage

استخدام وحدة تحكّم Firebase

يمكنك أيضًا تعديل Rules المصادر ونشرها كإصدارات من وحدة تحكّم Firebase. يتم إجراء الاختبار النحوي أثناء التعديل في واجهة مستخدم وحدة التحكّم Firebase، ويتوفّر الاختبار الدلالي باستخدام Rules Playground.

تعديل قواعدك وتحديثها

  1. افتح Firebase وحدة التحكّم واختَر مشروعك.
  2. بعد ذلك، اختَر Realtime Database أو Cloud Firestore أو التخزين من قائمة التنقّل في المنتج، ثم انقر على القواعد للانتقال إلى محرّر Rules.
  3. عدِّل قواعدك مباشرةً في المحرّر.

اختبار التحديثات

بالإضافة إلى اختبار البنية في واجهة مستخدم المحرّر، يمكنك اختبار سلوك Rules الدلالات باستخدام موارد قاعدة البيانات والتخزين الخاصة بمشروعك مباشرةً في وحدة تحكّم Firebase باستخدام Rules Playground. افتح شاشة Rules Playground في محرّر Rules، وعدِّل الإعدادات وانقر على تشغيل. ابحث عن رسالة التأكيد في أعلى المحرِّر.

نشر التحديثات

بعد التأكّد من أنّ التعديلات هي ما تتوقّعه، انقر على نشر.

استخدام حزمة SDK للمشرف

يمكنك استخدام Admin SDKمجموعات القواعد الخاصة بـ Node.js. باستخدام إذن الوصول الآلي هذا، يمكنك إجراء ما يلي:

  • تنفيذ أدوات ونصوص برمجية ولوحات بيانات وقنوات CI/CD مخصّصة لإدارة القواعد
  • إدارة القواعد بسهولة أكبر في مشاريع Firebase متعددة

عند تعديل القواعد آليًا، من المهم جدًا تجنُّب إجراء تغييرات غير مقصودة على عناصر التحكّم في الوصول إلى تطبيقك. لذا، احرص على كتابة Admin SDK الرمز البرمجيAdmin SDK مع مراعاة الأمان في المقام الأول، خاصةً عند تعديل القواعد أو نشرها.

من المهم أيضًا أن تتذكّر أنّ إصدارات Firebase Security Rules تستغرق عدة دقائق حتى يتم نشرها بالكامل. عند استخدام Admin SDK لنشر القواعد، احرص على تجنُّب حالات التزامن التي يعتمد فيها تطبيقك على الفور على قواعد لم يكتمل نشرها بعد. إذا كانت حالة الاستخدام تتطلّب تعديلات متكرّرة على قواعد التحكّم في الوصول، ننصحك باستخدام حلول تستخدم Cloud Firestore، المصمَّمة للحدّ من حالات التعارض على الرغم من التعديلات المتكرّرة.

يُرجى أيضًا ملاحظة الحدود التالية:

  • يجب أن يكون حجم القواعد أقل من 256 كيلوبايت من النص المرمّز بنظام UTF-8 عند تسلسله.
  • يمكن أن يحتوي المشروع على 2500 مجموعة قواعد تم نشرها كحدّ أقصى. وبعد بلوغ هذا الحدّ، عليك حذف بعض مجموعات القواعد القديمة قبل إنشاء مجموعات جديدة.

إنشاء مجموعات قواعد Cloud Storage أو Cloud Firestore ونشرها

يمكن أن تتضمّن عملية سير العمل النموذجية لإدارة قواعد الأمان باستخدام Admin SDK ثلاث خطوات منفصلة:

  1. إنشاء مصدر ملف قواعد (اختياري)
  2. إنشاء مجموعة قواعد
  3. إصدار مجموعة القواعد الجديدة أو نشرها

توفّر حزمة SDK طريقة لدمج هذه الخطوات في طلب واحد من واجهة برمجة التطبيقات لقواعد الأمان Cloud Storage وCloud Firestore. على سبيل المثال:

    const source = `service cloud.firestore {
      match /databases/{database}/documents {
        match /carts/{cartID} {
          allow create: if request.auth != null && request.auth.uid == request.resource.data.ownerUID;
          allow read, update, delete: if request.auth != null && request.auth.uid == resource.data.ownerUID;
        }
      }
    }`;
    // Alternatively, load rules from a file
    // const fs = require('fs');
    // const source = fs.readFileSync('path/to/firestore.rules', 'utf8');

    await admin.securityRules().releaseFirestoreRulesetFromSource(source);

يعمل النمط نفسه مع قواعد Cloud Storage التي تتضمّن releaseFirestoreRulesetFromSource().

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

    const rf = admin.securityRules().createRulesFileFromSource('firestore.rules', source);
    const rs = await admin.securityRules().createRuleset(rf);
    await admin.securityRules().releaseFirestoreRuleset(rs);

تعديل Realtime Database مجموعات قواعد

لتعديل مجموعات قواعد Realtime Database باستخدام Admin SDK، استخدِم طريقتَي getRules() وsetRules() من admin.database. يمكنك استرداد مجموعات القواعد بتنسيق JSON أو كسلسلة تتضمّن تعليقات.

لتعديل مجموعة قواعد، اتّبِع الخطوات التالية:

    const source = `{
      "rules": {
        "scores": {
          ".indexOn": "score",
          "$uid": {
            ".read": "$uid == auth.uid",
            ".write": "$uid == auth.uid"
          }
        }
      }
    }`;
    await admin.database().setRules(source);

إدارة مجموعات القواعد

للمساعدة في إدارة مجموعات القواعد الكبيرة، تتيح لك Admin SDK إدراج جميع القواعد الحالية باستخدام admin.securityRules().listRulesetMetadata. على سبيل المثال:

    const allRulesets = [];
    let pageToken = null;
    while (true) {
      const result = await admin.securityRules().listRulesetMetadata(pageToken: pageToken);
      allRulesets.push(...result.rulesets);
      pageToken = result.nextPageToken;
      if (!pageToken) {
        break;
      }
    }

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

    const thirtyDays = new Date(Date.now() - THIRTY_DAYS_IN_MILLIS);
    const promises = [];
    allRulesets.forEach((rs) => {
      if (new Date(rs.createTime) < thirtyDays) {
        promises.push(admin.securityRules().deleteRuleset(rs.name));
      }
    });
    await Promise.all(promises);
    console.log(`Deleted ${promises.length} rulesets.`);

استخدام REST API

إنّ الأدوات الموضّحة أعلاه مناسبة تمامًا لمختلف سير العمل، بما في ذلك إدارة Firebase Security Rules لقواعد بيانات Cloud Firestore متعددة في مشروعك، ولكن قد تحتاج إلى إدارة Firebase Security Rules ونشره باستخدام واجهة برمجة التطبيقات الإدارية نفسها. تمنحك واجهة برمجة التطبيقات الإدارية أكبر قدر من المرونة.

يُرجى أيضًا ملاحظة الحدود التالية:

  • يجب أن يكون حجم القواعد أقل من 256 كيلوبايت من النص المرمّز بنظام UTF-8 عند تسلسله.
  • يمكن أن يحتوي المشروع على 2500 مجموعة قواعد تم نشرها كحدّ أقصى. وبعد بلوغ هذا الحدّ، عليك حذف بعض مجموعات القواعد القديمة قبل إنشاء مجموعات جديدة.

إنشاء مجموعات قواعد Cloud Firestore أو Cloud Storage ونشرها باستخدام REST

تستخدِم الأمثلة في هذا القسم Firestore Rules، ولكنّها تنطبق أيضًا على Cloud Storage Rules.

تستخدِم الأمثلة أيضًا cURL لإجراء طلبات البيانات من واجهة برمجة التطبيقات. تم حذف خطوات إعداد رموز المصادقة وتمريرها. يمكنك تجربة هذه الواجهة باستخدام API Explorer المدمج مع المستندات المرجعية.

في ما يلي الخطوات النموذجية لإنشاء مجموعة قواعد ونشرها باستخدام Management API:

  1. إنشاء مصادر ملفات القواعد
  2. إنشاء مجموعة قواعد
  3. أصدِر (نفِّذ) مجموعة القواعد الجديدة.

إنشاء مستند مصدر

لنفترض أنّك تعمل على secure_commerce مشروع Firebase وتريد نشر Cloud Firestore Rules محمي في قاعدة بيانات في مشروعك باسم east_store.

يمكنك تنفيذ هذه القواعد في ملف firestore.rules.

service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

إنشاء مجموعة قواعد

الآن، أنشئ ملفًا مرجعيًا بترميز base64 لهذا الملف. يمكنك بعد ذلك استخدام المصدر في هذا الملف لتعبئة الحمولة اللازمة لإنشاء مجموعة قواعد باستخدام طلب projects.rulesets.create REST. في هذه الحالة، استخدِم الأمر cat لإدراج محتوى firestore.rules في حمولة REST.

للتتبُّع، لربط هذا الحقل بقاعدة بيانات east_store، اضبط قيمة attachment_point على east_store.

curl -X POST -d '{
  "source": {
    "files": [
      {
        "content": "' $(cat storage.rules) '",
        "name": "firestore.rules",
        "fingerprint": <sha fingerprint>
      },
    "attachment_point": "firestore.googleapis.com/databases/east_store"
    ]
  }
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets'

تعرض واجهة برمجة التطبيقات ردًّا للتحقّق من الصحة واسم مجموعة قواعد، مثل projects/secure_commerce/rulesets/uuid123.

إصدار (نشر) مجموعة قواعد

إذا كانت مجموعة القواعد صالحة، تكون الخطوة الأخيرة هي نشر مجموعة القواعد الجديدة في إصدار يحمل اسمًا.

curl -X POST -d '{
  "name": "projects/secure_commerce/releases/cloud.firestore/east_store"  ,
  "rulesetName": "projects/secure_commerce/rulesets/uuid123"
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/releases'

يُرجى العِلم أنّ إصدارات Firebase Security Rules تستغرق عدة دقائق ليتم نشرها بالكامل. عند استخدام واجهة برمجة التطبيقات REST الخاصة بالإدارة للنشر، احرص على تجنُّب حالات التنافس التي يعتمد فيها تطبيقك على الفور على قواعد لم يكتمل نشرها بعد.

تعديل مجموعات قواعد Realtime Database باستخدام REST

توفّر Realtime Database واجهة REST الخاصة بها لإدارة Rules. اطّلِع على إدارة Realtime Database Rules Firebase من خلال REST.

إدارة مجموعات القواعد باستخدام REST

للمساعدة في إدارة عمليات نشر القواعد الكبيرة، بالإضافة إلى طريقة REST لإنشاء مجموعات القواعد والإصدارات، توفّر واجهة برمجة التطبيقات الإدارية طرقًا لإجراء ما يلي:

  • إدراج مجموعات القواعد والحصول عليها وحذفها
  • عرض الإصدارات في قائمة والحصول عليها وحذفها

بالنسبة إلى عمليات النشر الكبيرة جدًا التي تصل إلى الحدّ الأقصى البالغ 2500 مجموعة قواعد بمرور الوقت، يمكنك إنشاء منطق لحذف أقدم القواعد في دورة زمنية ثابتة. على سبيل المثال، لحذف جميع مجموعات القواعد التي تم نشرها لمدة تزيد عن 30 يومًا، يمكنك استدعاء الطريقة projects.rulesets.list، وتحليل قائمة JSON الخاصة بكائنات Ruleset على مفاتيح createTime، ثم استدعاء project.rulesets.delete على مجموعات القواعد المقابلة حسب ruleset_id.

اختبار التحديثات باستخدام REST

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

يتضمّن الاختبار باستخدام هذا المكوّن من واجهة برمجة التطبيقات ما يلي:

  1. تحديد عنصر JSON TestSuite لتمثيل مجموعة من عناصر TestCase
  2. جارٍ إرسال TestSuite
  3. تحليل TestResult عنصر تم إرجاعه

لنحدّد كائن TestSuite يحتوي على TestCase واحد في ملف testcase.json. في هذا المثال، نمرّر مصدر اللغة Rules ضمن حمولة REST، بالإضافة إلى مجموعة الاختبارات التي سيتم تنفيذها على هذه القواعد. نحدّد توقعات تقييم القواعد، ونحدّد طلب العميل الذي سيتم اختبار مجموعة القواعد مقابله. يمكنك أيضًا تحديد مدى اكتمال تقرير الاختبار، وذلك باستخدام القيمة "FULL" للإشارة إلى أنّه يجب تضمين نتائج جميع عبارات اللغة Rules في التقرير، بما في ذلك العبارات التي لم تتم مطابقتها مع الطلب.

 {
  "source":
  {
    "files":
    [
      {
        "name": "firestore.rules",
        "content": "service cloud.firestore {
          match /databases/{database}/documents {
            match /users/{userId}{
              allow read: if (request.auth.uid == userId);
            }
            function doc(subpath) {
              return get(/databases/$(database)/documents/$(subpath)).data;
            }
            function isAccountOwner(accountId) {
              return request.auth.uid == accountId 
                  || doc(/users/$(request.auth.uid)).accountId == accountId;
            }
            match /licenses/{accountId} {
              allow read: if isAccountOwner(accountId);
            }
          }
        }"
      }
    ]
  },
  "testSuite":
  {
    "testCases":
    [
      {
        "expectation": "ALLOW",
        "request": {
           "auth": {"uid": "123"},
           "path": "/databases/(default)/documents/licenses/abcd",
           "method": "get"},
        "functionMocks": [
            {
            "function": "get",
            "args": [{"exact_value": "/databases/(default)/documents/users/123"}],
            "result": {"value": {"data": {"accountId": "abcd"}}}
            }
          ]
      }
    ]
  }
}

يمكننا بعد ذلك إرسال هذا TestSuite للتقييم باستخدام طريقة projects.test.

curl -X POST -d '{
    ' $(cat testcase.json) '
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets/uuid123:test'

سيؤكّد الرمز TestReport الذي تم إرجاعه (والذي يتضمّن حالة النجاح/الفشل في الاختبار، وقوائم رسائل تصحيح الأخطاء، وقوائم تعبيرات القواعد التي تمت زيارتها وتقارير تقييمها) أنّ الإذن بالوصول قد تم منحه بشكل صحيح، وذلك من خلال الحالة SUCCESS.

إدارة أذونات Cloud Storage Security Rules على مستوى الخدمات

إذا أنشأت Cloud Storage Security Rules تستخدم محتوى مستند Cloud Firestore لتقييم شروط الأمان، سيُطلب منك في وحدة تحكّم Firebase أو واجهة سطر الأوامر Firebase تفعيل الأذونات لربط المنتجين.

في حال قررت إيقاف هذا النوع من الأمان على مستوى الخدمات:

  1. قبل إيقاف الميزة، عليك أولاً تعديل قواعدك وإزالة جميع العبارات التي تستخدم دوال Rules للوصول إلى Cloud Firestore. وفي حال عدم توفّرها، ستؤدي تقييمات Rules إلى تعذُّر إرسال طلبات الحصول على مساحة تخزين بعد إيقاف الميزة.

  2. استخدِم صفحة إدارة الهوية وإمكانية الوصول في Google Cloud Console لحذف دور "وكيل خدمة Firebase Rules Firestore" باتّباع دليل Cloud لإبطال الأدوار.

سيُطلب منك إعادة تفعيل الميزة في المرة التالية التي تحفظ فيها قواعد الخدمات المتعددة من واجهة سطر الأوامر (CLI) في Firebase أو وحدة تحكّم Firebase.