Firebase מספקת לך מספר כלים לניהול הכללים שלך, כל אחד שימושי במקרים מסוימים, וכל אחד משתמש באותו ממשק API לניהול כללי אבטחה של Firebase.
לא משנה באיזה כלי משתמשים כדי להפעיל אותו, ממשק ה-API לניהול:
- קולט מקור כללים : קבוצה של כללים, בדרך כלל קובץ קוד המכיל הצהרות כללי אבטחה של Firebase.
- מאחסן מקור שנבלע כמערכת כללים בלתי ניתנת לשינוי.
- עוקב אחר פריסה של כל ערכת כללים במהדורה . שירותים התומכים בחוקי אבטחה של Firebase מחפשים את המהדורה עבור פרויקט כדי להעריך כל בקשה למשאב מאובטח.
- מספק את היכולת להפעיל בדיקות תחביריות וסמנטיות של ערכת חוקים.
השתמש ב-Firebase CLI
עם Firebase CLI , אתה יכול להעלות מקורות מקומיים ולפרוס מהדורות . Firebase Local Emulator Suite של ה-CLI מאפשר לך לבצע בדיקות מקומיות מלאות של מקורות .
השימוש ב-CLI מאפשר לך לשמור על הכללים שלך תחת בקרת גרסאות עם קוד היישום שלך ולפרוס כללים כחלק מתהליך הפריסה הקיים שלך.
צור קובץ תצורה
כאשר אתה מגדיר את פרויקט Firebase שלך באמצעות Firebase CLI, אתה יוצר קובץ תצורה .rules
בספריית הפרויקט שלך. השתמש בפקודה הבאה כדי להתחיל להגדיר את פרויקט Firebase שלך:
Cloud 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.
בדוק את העדכונים שלך
חבילת האימולטור המקומי מספקת אמולטורים עבור כל המוצרים התומכים בחוקי אבטחה. מנוע כללי האבטחה עבור כל אמולטור מבצע הן הערכה תחבירית והן סמנטית של כללים, ובכך חורג מהבדיקות התחביריות שמציע ה-API לניהול כללי האבטחה.
אם אתה עובד עם ה-CLI, הסוויטה היא כלי מצוין לבדיקת כללי אבטחה של Firebase. השתמש ב- Local Emulator Suite כדי לבדוק את העדכונים שלך באופן מקומי ולאשר שהכללים של האפליקציה שלך מציגים את ההתנהגות הרצויה.
פרוס את העדכונים שלך
לאחר שעדכנת ובדקת את הכללים שלך, פרוס את המקורות לייצור.
עבור כללי האבטחה של Cloud Firestore, שייך את קובצי .rules
לבסיסי הנתונים המוגדרים כברירת מחדל ולמסדי נתונים נוספים בשם על ידי סקירה ועדכון של קובץ firebase.json
שלך.
השתמש בפקודות הבאות כדי לפרוס באופן סלקטיבי את הכללים שלך לבד או לפרוס אותם כחלק מתהליך הפריסה הרגיל שלך.
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>
מסד נתונים בזמן אמת
// Deploy your .rules file firebase deploy --only database
אחסון בענן
// Deploy your .rules file firebase deploy --only storage
השתמש במסוף Firebase
אתה יכול גם לערוך מקורות של כללים ולפרוס אותם כגרסאות ממסוף Firebase. בדיקות תחביריות מבוצעות תוך כדי עריכה בממשק המשתמש של קונסולת Firebase, ובדיקות סמנטיות זמינות באמצעות Rules Playground.
ערוך ועדכן את הכללים שלך
- פתח את מסוף Firebase ובחר בפרויקט שלך.
- לאחר מכן, בחר מסד נתונים בזמן אמת , Cloud Firestore או Storage מניווט המוצר, ולאחר מכן לחץ על כללים כדי לנווט אל עורך הכללים.
- ערוך את הכללים שלך ישירות בעורך.
בדוק את העדכונים שלך
בנוסף לבדיקת תחביר בממשק המשתמש של העורך, אתה יכול לבדוק את התנהגות הכללים הסמנטיים, תוך שימוש במסד הנתונים ובמשאבי האחסון של הפרויקט שלך, ישירות במסוף Firebase, באמצעות Rules Playground . פתח את מסך Rules Playground בעורך הכללים, שנה את ההגדרות ולחץ על הפעל . חפש את הודעת האישור בחלק העליון של העורך.
פרוס את העדכונים שלך
לאחר שתהיה מרוצה שהעדכונים שלך הם מה שאתה מצפה, לחץ על פרסם .
השתמש ב-Admin SDK
אתה יכול להשתמש ב-Admin SDK עבור ערכות כללים של Node.js. עם גישה פרוגרמטית זו, אתה יכול:
- הטמע כלים מותאמים אישית, סקריפטים, לוחות מחוונים וצינורות CI/CD לניהול כללים.
- נהל כללים ביתר קלות בפרוייקטים מרובים של Firebase.
בעת עדכון כללים באופן פרוגרמטי, חשוב מאוד להימנע מביצוע שינויים לא מכוונים בבקרת הגישה של האפליקציה שלך. כתוב את קוד ה-SDK של Admin מתוך מחשבה על אבטחה, במיוחד בעת עדכון או פריסה של כללים.
דבר נוסף שחשוב לזכור הוא שלשחרור כללי האבטחה של Firebase לוקח פרק זמן של מספר דקות להתפשט במלואו. בעת שימוש ב-Admin SDK לפריסת כללים, הקפד להימנע מתנאי מרוץ שבהם האפליקציה שלך מסתמכת באופן מיידי על כללים שהפריסה שלהם עדיין לא הושלמה. אם מקרה השימוש שלך דורש עדכונים תכופים לכללי בקרת הגישה, שקול פתרונות המשתמשים ב-Cloud Firestore, שנועד לצמצם את תנאי המירוץ למרות עדכונים תכופים.
שימו לב גם למגבלות אלו:
- הכללים חייבים להיות קטנים מ-256 KiB של טקסט מקודד UTF-8 כאשר הם מסודרים.
- לפרוייקט יכולים להיות לכל היותר 2,500 כללים פרוסים בסך הכל. לאחר הגבלה זו, עליך למחוק כמה ערכות כללים ישנות לפני יצירת חדשות.
צור ופריסה ערכות כללים של Cloud Storage או Cloud Firestore
זרימת עבודה טיפוסית לניהול כללי אבטחה עם ה-Admin SDK יכולה לכלול שלושה שלבים נפרדים:
- צור מקור קובץ כללים (אופציונלי)
- צור ערכת כללים
- שחרר, או פרוס, את ערכת הכללים החדשה
ה-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);
אותו דפוס עובד עבור כללי Cloud Storage עם releaseFirestoreRulesetFromSource()
.
לחלופין, ניתן ליצור את קובץ הכללים כאובייקט בזיכרון, ליצור את ערכת הכללים ולפרוס את ערכת הכללים בנפרד לשליטה קרובה יותר על אירועים אלה. לדוגמה:
const rf = admin.securityRules().createRulesFileFromSource('firestore.rules', source);
const rs = await admin.securityRules().createRuleset(rf);
await admin.securityRules().releaseFirestoreRuleset(rs);
עדכן ערכות חוקים של מסד נתונים בזמן אמת
כדי לעדכן ערכות חוקים של מסד נתונים בזמן אמת עם ה-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 עבור מסדי נתונים מרובים של Cloud Firestore בפרויקט שלך, אך ייתכן שתרצה לנהל ולפרוס את כללי האבטחה של Firebase באמצעות ממשק ה-API לניהול עצמו. ממשק ה-API לניהול נותן לך את הגמישות הגדולה ביותר.
שימו לב גם למגבלות אלו:
- הכללים חייבים להיות קטנים מ-256 KiB של טקסט מקודד UTF-8 כאשר הם מסודרים.
- לפרוייקט יכולים להיות לכל היותר 2,500 כללים פרוסים בסך הכל. לאחר הגבלה זו, עליך למחוק כמה ערכות כללים ישנות לפני יצירת חדשות.
צור ופריסה ערכות כללים של Cloud Firestore או Cloud Storage עם REST
הדוגמאות בסעיף זה משתמשות בכללי Firestore, אם כי הם חלים גם על כללי אחסון בענן.
הדוגמאות משתמשות גם ב-cURL כדי לבצע קריאות API. הושמטו שלבים להגדרה והעברת אסימוני אימות. אתה יכול להתנסות עם API זה באמצעות API Explorer המשולב בתיעוד העזר.
השלבים האופייניים ליצירה ופריסה של ערכת כללים באמצעות ממשק API לניהול הם:
- צור מקורות קבצי כללים
- צור ערכת כללים
- שחרר (פרוס) את ערכת הכללים החדשה.
צור מקור
נניח שאתה עובד על פרויקט 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
מסד נתונים בזמן אמת מספק ממשק REST משלו לניהול כללים. ראה ניהול כללי מסד נתונים של Firebase בזמן אמת באמצעות REST .
נהל ערכות כללים עם REST
כדי לסייע בניהול פריסות כללים גדולות, בנוסף לשיטת REST ליצירת ערכות כללים ומהדורות, ממשק API לניהול מספק שיטות ל:
- רשום, קבל ומחק ערכות כללים
- רשום, קבל ומחק גרסאות כללים
עבור פריסות גדולות מאוד שמגיעות למגבלה של 2500 ערכות כללים לאורך זמן, אתה יכול ליצור היגיון למחיקת הכללים הישנים ביותר במחזור זמן קבוע. לדוגמה, כדי למחוק את כל ערכות הכללים שנפרסו במשך יותר מ-30 יום, אתה יכול לקרוא למתודה projects.rulesets.list
, לנתח את רשימת ה-JSON של אובייקטי Ruleset
במפתחות createTime
שלהם, ואז לקרוא ל- project.rulesets.delete
בערכות הכללים המתאימות לפי ruleset_id
.
בדוק את העדכונים שלך עם REST
לבסוף, ממשק ה-API לניהול מאפשר לך להריץ בדיקות תחביריות וסמנטיות על משאבי Cloud Firestore ו-Cloud Storage בפרויקטי הייצור שלך.
בדיקה עם רכיב זה של ה-API מורכבת מ:
- הגדרת אובייקט
TestSuite
JSON לייצג קבוצה של אובייקטיםTestCase
- הגשת ה-
TestSuite
- ניתוח אובייקטי
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
שהוחזר (המכיל את סטטוס הבדיקה SUCCESS/FAILURE, רשימות של הודעות ניפוי באגים, רשימות של ביטויי כללים שביקרו בהם ודוחות ההערכה שלהם) יאשר עם הסטטוס SUCCESS שהגישה מותרת כהלכה.
נהל הרשאות עבור כללי אבטחה חוצי שירות בענן אחסון ענן
אם אתה יוצר כללי אבטחה של Cloud Storage המשתמשים בתוכן מסמכי Cloud Firestore כדי להעריך תנאי אבטחה , תתבקש במסוף Firebase או Firebase CLI לאפשר הרשאות לחיבור שני המוצרים.
אם תחליט להשבית אבטחה צולבת שירותים כזו:
ראשית, לפני השבתת התכונה, ערוך את הכללים שלך, והסר את כל ההצהרות המשתמשות בפונקציות Rules כדי לגשת ל-Cloud Firestore. אחרת, לאחר השבתת התכונה, הערכות כללים יגרמו לבקשות האחסון שלך להיכשל.
השתמש בדף IAM ב-Google Cloud Console כדי למחוק את התפקיד "Firebase Rules Firestore Service Agent" על ידי ביצוע מדריך הענן לביטול תפקידים .
תתבקש להפעיל מחדש את התכונה בפעם הבאה שתשמור חוקים צולבים מה-CLI של Firebase או ממסוף Firebase.