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

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

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

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

استخدام سطر أوامر Firebase

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

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

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

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

Cloud Firestore 

// Set up Firestore in your project directory, creates a .rules file
firebase init firestore

Realtime Database 

// Set up Realtime Database in your project directory, creates a .rules file
firebase init database

Cloud Storage 

// Set up Storage in your project directory, creates a .rules file
firebase init storage

تعديل قواعدك

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

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

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

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

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

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

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

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

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

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

Realtime Database 

// Deploy your .rules file
firebase deploy --only database

Cloud Storage 

// Deploy your .rules file
firebase deploy --only storage

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

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

تعديل قواعدك

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

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

بالإضافة إلى اختبار البنية في واجهة مستخدم المحرِّر، يمكنك اختبار السلوك الدلالي Rules باستخدام قاعدة بيانات مشروعك وموارد التخزين، مباشرةً في وحدة تحكّم Firebase، باستخدام Rules ساحة اللعب. افتح شاشة Rules Playground (مساحة اختبار القواعد) في محرِّر Rules، عدِّل الإعدادات وانقر على 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 طريقة لدمج هذه الخطوات في طلب واحد للحصول على البيانات من واجهة برمجة التطبيقات لقواعد أمان 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

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

يُرجى أيضًا مراعاة هذه الحدود:

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

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

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

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

في ما يلي الخطوات المعتادة لإنشاء مجموعة قواعد ونشرها باستخدام 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 لهذا الملف. يمكنك بعد ذلك استخدام source في هذا الملف لتعبئة الحمولة المطلوبة لإنشاء مجموعة قواعد باستخدام projects.rulesets.create طلب REST. في هذه الحالة، استخدِم الأمر cat لإدراج محتوى firestore.rules في حمولة طلب REST.

للتتبُّع، اضبط attachment_point على east_store لربط هذا الإجراء بقاعدة بيانات 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 تستغرق عدة دقائق لتتم نشرها بالكامل. عند استخدام Management REST API للنشر، احرص على تجنُّب حالات التداخل التي يعتمد فيها تطبيقك على الفور على قواعد لم يكتمل نشرها بعد.

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

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

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

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

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

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

اختبار التعديلات باستخدام REST

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

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

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

لنحدِّد عنصر TestSuite يتضمّن TestCase واحدًا في ملف testcase.json. في هذا المثال، نُرسل Rules مصدر اللغة مضمّنًا في الحمولة البرمجية لبروتوكول REST، إلى جانب مجموعة الاختبار لتنفيذ هذه القواعد. نحدّد توقّعًا لتقييم القواعد، وطلب العميل الذي سيتم اختبار مجموعة القواعد وفقًا له. يمكنك أيضًا تحديد مدى اكتمال تقرير الاختبار، باستخدام القيمة "كامل" للإشارة إلى نتائج جميع عبارات اللغة 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 الذي تم إرجاعه (الذي يحتوي على حالة الاختبار "نجاح/تعذُّر" وقوائم برسائل debugging و قوائم بتعبيرات القواعد التي تمّ زيارتها وتقارير تقييمها) بحالة "نجاح" أنّه تمّ السماح بالوصول بشكلٍ صحيح.

إدارة الأذونات لتطبيق Cloud Storage Security Rules على جميع الخدمات

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

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

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

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

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