Catch up on highlights from Firebase at Google I/O 2023. Learn more

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

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

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

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

استخدم Firebase CLI

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

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

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

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

سحابة Firestore

// 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 وتحديثه.

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

سحابة Firestore

// 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 ، باستخدام " ساحة اللعب القواعد" . افتح شاشة ساحة اللعب في محرر القواعد ، وقم بتعديل الإعدادات وانقر فوق تشغيل . ابحث عن رسالة التأكيد أعلى المحرر.

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

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

استخدم Admin SDK

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

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

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

شيء آخر مهم يجب أخذه في الاعتبار هو أن إصدارات قواعد أمان Firebase تستغرق عدة دقائق لنشرها بالكامل. عند استخدام 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);

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

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

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

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

لتحديث مجموعات قواعد 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

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

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

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

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

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

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

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

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

قم بإنشاء مصدر

لنفترض أنك تعمل على مشروع Firebase secure_commerce وتريد نشر قواعد Cloud Firestore المؤمّنة إلى قاعدة بيانات في مشروعك باسم 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'

تُرجع واجهة برمجة التطبيقات (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 للنشر ، تأكد من تجنب ظروف السباق التي يعتمد فيها تطبيقك فورًا على القواعد التي لم يكتمل نشرها بعد.

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

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

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

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

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

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

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

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

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

  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 Firestore لتقييم ظروف الأمان ، فستتم مطالبتك في وحدة تحكم Firebase أو Firebase CLI لتمكين الأذونات لربط المنتجين.

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

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

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

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