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

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

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

  • يستوعب مصدر القواعد: مجموعة من القواعد، عادةً ما يكون ملف تعليمات برمجية يحتوي على بيانات قواعد أمان Firebase.
  • يخزن المصدر المبتلع كمجموعة قواعد غير قابلة للتغيير.
  • يتتبع نشر كل مجموعة قواعد في الإصدار . تبحث الخدمات التي تدعم قواعد أمان Firebase عن إصدار مشروع لتقييم كل طلب لمورد آمن.
  • يوفر القدرة على تشغيل الاختبارات النحوية والدلالية لمجموعة القواعد.

استخدم Firebase CLI

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

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

إنشاء ملف التكوين

عندما تقوم بتكوين مشروع Firebase الخاص بك باستخدام Firebase CLI، فإنك تقوم بإنشاء ملف تكوين .rules في دليل المشروع الخاص بك. استخدم الأمر التالي لبدء تكوين مشروع Firebase الخاص بك:

سحابة فايرستور

// 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 CLI تنعكس في وحدة تحكم Firebase، أو أنك تجري تحديثات باستمرار باستخدام وحدة تحكم Firebase أو Firebase CLI. وإلا، فقد تقوم بالكتابة فوق أي تحديثات تم إجراؤها في وحدة تحكم Firebase.

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

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

إذا كنت تعمل مع واجهة سطر الأوامر (CLI)، فإن Suite يعد أداة ممتازة لاختبار قواعد أمان Firebase. استخدم Local Emulator Suite لاختبار تحديثاتك محليًا والتأكد من أن قواعد تطبيقك تظهر السلوك الذي تريده.

نشر التحديثات الخاصة بك

بمجرد تحديث القواعد الخاصة بك واختبارها، قم بنشر المصادر إلى الإنتاج.

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

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

سحابة فايرستور

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

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

تحرير وتحديث القواعد الخاصة بك

  1. افتح وحدة تحكم Firebase وحدد مشروعك.
  2. بعد ذلك، حدد Realtime Database أو Cloud Firestore أو Storage من شريط التنقل الخاص بالمنتج، ثم انقر فوق "القواعد" للانتقال إلى محرر القواعد.
  3. قم بتحرير القواعد الخاصة بك مباشرة في المحرر.

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

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

نشر التحديثات الخاصة بك

بمجرد أن تقتنع بأن تحديثاتك هي ما تتوقعه، انقر فوق نشر .

استخدم SDK للمشرف

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

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

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

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

لاحظ أيضًا هذه الحدود:

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

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

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

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

يوفر SDK طريقة لدمج هذه الخطوات في استدعاء API واحد لقواعد أمان 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);

يعمل هذا النمط نفسه مع قواعد التخزين السحابي باستخدام releaseFirestoreRulesetFromSource() .

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

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

تحديث مجموعات قواعد قاعدة البيانات في الوقت الفعلي

لتحديث مجموعات قواعد قاعدة بيانات Realtime باستخدام 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

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

لاحظ أيضًا هذه الحدود:

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

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

تستخدم الأمثلة الواردة في هذا القسم قواعد Firestore، على الرغم من أنها تنطبق على قواعد التخزين السحابي أيضًا.

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

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

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

إنشاء مصدر

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

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

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

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

الآن، قم بإنشاء بصمة مشفرة بـ base64 لهذا الملف. يمكنك بعد ذلك استخدام المصدر الموجود في هذا الملف لملء الحمولة اللازمة لإنشاء مجموعة قواعد باستخدام استدعاء REST projects.rulesets.create . هنا، استخدم الأمر 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'

تقوم واجهة برمجة التطبيقات (API) بإرجاع استجابة التحقق من الصحة واسم مجموعة القواعد، على سبيل المثال 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 تستغرق عدة دقائق حتى يتم نشرها بالكامل. عند استخدام إدارة REST API للنشر، تأكد من تجنب حالات السباق التي يعتمد فيها تطبيقك على الفور على القواعد التي لم يكتمل نشرها بعد.

قم بتحديث مجموعات قواعد قاعدة البيانات في الوقت الفعلي باستخدام REST

توفر قاعدة بيانات Realtime واجهة REST الخاصة بها لإدارة القواعد. راجع إدارة قواعد قاعدة بيانات Firebase Realtime عبر REST .

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

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

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

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

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

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

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

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

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

 {
  "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 الذي تم إرجاعه (الذي يحتوي على حالة نجاح/فشل الاختبار وقوائم رسائل تصحيح الأخطاء وقوائم تعبيرات القواعد التي تمت زيارتها وتقارير التقييم الخاصة بها) من خلال حالة النجاح أن الوصول مسموح به بشكل صحيح.

إدارة الأذونات لقواعد أمان التخزين السحابي عبر الخدمات

إذا قمت بإنشاء قواعد أمان Cloud Storage التي تستخدم محتويات مستند Cloud Firestore لتقييم ظروف الأمان ، فستتم مطالبتك في وحدة تحكم Firebase أو Firebase CLI لتمكين الأذونات لتوصيل المنتجين.

إذا قررت تعطيل هذا الأمان عبر الخدمات:

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

  2. استخدم صفحة IAM في Google Cloud Console لحذف دور "Firebase Rules Firestore Service Agent" باتباع دليل Cloud لإلغاء الأدوار .

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