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

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

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

  • استيعاب مصدر القواعد: مجموعة من القواعد ، عادةً ما تكون ملف رمز يحتوي على عبارات قواعد أمان 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 لاختبار تحديثاتك محليًا والتأكد من أن قواعد التطبيق تُظهر السلوك الذي تريده.

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

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

سحابة Firestore

// Deploy your .rules file
firebase deploy --only firestore:rules

قاعدة بيانات الوقت الحقيقي

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

اعلم أن إصدارات قواعد أمان Firebase تستغرق عدة دقائق لنشرها بالكامل. عند استخدام واجهة برمجة تطبيقات الإدارة REST للنشر ، تأكد من تجنب ظروف السباق التي يعتمد فيها تطبيقك فورًا على القواعد التي لم يكتمل نشرها بعد.

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

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

قم بإنشاء ونشر Cloud Storage أو Cloud Firestore مع REST

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

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

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

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

لنفترض أنك تعمل على مشروع secure_commerce وتريد نشر قواعد التخزين السحابي المؤمّنة. يمكنك تنفيذ هذه القواعد في ملف storage.rules .

service firebase.storage {
  match /b/{bucket}/o {
    match /{allPaths=**} {
      allow read, write: if false;
    }
  }
}

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

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

تُرجع واجهة برمجة التطبيقات (API) استجابة التحقق واسم مجموعة القواعد ، على سبيل المثال projects/secure_commerce/rulesets/uuid123 . إذا كانت مجموعة القواعد صالحة ، فإن الخطوة الأخيرة هي نشر مجموعة القواعد الجديدة في إصدار مسمى.

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

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

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

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

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

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

لعمليات النشر الكبيرة جدًا التي تصل إلى 2500 مجموعة قواعد بمرور الوقت ، يمكنك إنشاء منطق لحذف أقدم القواعد في دورة زمنية محددة. على سبيل المثال ، لحذف جميع مجموعات القواعد التي تم نشرها لمدة تزيد عن 30 يومًا ، يمكنك استدعاء طريقة projects.rulesets.list ، تحليل قائمة JSON لكائنات مجموعة createTime Ruleset بهم ، ثم استدعاء 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 (الذي يحتوي على حالة نجاح / فشل الاختبار ، وقوائم رسائل التصحيح ، وقوائم تعبيرات القواعد التي تمت زيارتها وتقارير التقييم الخاصة بها) بالحالة نجاح أن الوصول مسموح به بشكل صحيح.