בדוק את כללי האבטחה של Cloud Firestore

כאשר אתה בונה את האפליקציה שלך, ייתכן שתרצה לנעול את הגישה למסד הנתונים של Cloud Firestore שלך. עם זאת, לפני שתפעיל, תזדקק לכללי האבטחה של Cloud Firestore בניואנסים יותר. עם אמולטור הענן Firestore, בנוסף prototyping והבדיקה של האפליקציה שלך תכונות והתנהגות כלליות , אתה יכול לכתוב בדיקות יחידות לבדוק את ההתנהגות של כללי אבטחת ענן Firestore שלך.

התחלה מהירה

יש כמה מקרים שבהם הבדיקה הבסיסית עם כללים פשוטים, לנסות את מדגם QuickStart .

הכרת כללי האבטחה של Cloud Firestore

יישום אימות Firebase ו ענן Firestore אבטחה כללים לאימות ללא שרת, אישור, ואימות נתונים בעת השימוש בספריות לקוח נייד ואינטרנט.

כללי האבטחה של Cloud Firestore כוללים שני חלקים:

  1. match הצהרה כי המסמכים מזהה במסד הנתונים.
  2. allow ביטוי כי בקרות גישה למסמכים אלה.

אימות Firebase מאמת את אישורי המשתמשים ומספק את הבסיס למערכות גישה מבוססות משתמשים ותפקידים.

כל בקשת מסד נתונים מספריית לקוח נייד/אינטרנט של Cloud Firestore מוערכת מול כללי האבטחה שלך לפני קריאה או כתיבה של נתונים כלשהם. אם הכללים מונעים גישה לאחד מנתיבי המסמך שצוינו, הבקשה כולה נכשלת.

למידע נוסף על ענן Firestore אבטחת כללי צעדים ראשון עם ענן Firestore כללי אבטחה .

התקן את האמולטור

כדי להתקין את האמולטור ענן Firestore, להשתמש Firebase CLI ולהפעיל את הפקודה הבאה:

firebase setup:emulators:firestore

הפעל את האמולטור

התחל באתחול של פרויקט Firebase בספריית העבודה שלך. זהו צעד ראשון נפוץ בעת שימוש Firebase CLI .

firebase init

הפעל את האמולטור באמצעות הפקודה הבאה. האמולטור יפעל עד שתחסל את התהליך:

firebase emulators:start --only firestore

במקרים רבים אתה רוצה להפעיל את האמולטור, להריץ חבילת בדיקות ולאחר מכן לכבות את האמולטור לאחר הפעלת הבדיקות. ניתן לעשות זאת בקלות באמצעות emulators:exec הפקודה:

firebase emulators:exec --only firestore "./my-test-script.sh"

כשהוא מופעל אמולטור ינסה לפעול ביציאת ברירת מחדל (8080). אתה יכול לשנות את יציאת אמולטור ידי שינוי "emulators" הקטע שלך firebase.json הקובץ:

{
  // ...
  "emulators": {
    "firestore": {
      "port": "YOUR_PORT"
    }
  }
}

לפני שאתה מפעיל את האמולטור

לפני שתתחיל להשתמש באמולטור, זכור את הדברים הבאים:

  • אמולטור בתחילה יטען הכללים המפורטים firestore.rules בתחום שלך firebase.json קובץ. הוא מצפה לשם של קובץ מקומי המכיל את כללי האבטחה של Cloud Firestore ומחיל את הכללים האלה על כל הפרויקטים. אם אתם לא מספקים את נתיב הקובץ המקומי או להשתמש loadFirestoreRules שיטה כמתואר להלן, פינוקים אמולטור כל הפרויקטים כבעל כללים פתוח.
  • בעוד רוב Firebase SDKs עבודה עם אמולטורים ישירות, רק @firebase/rules-unit-testing תומך ספרייה לועג auth בכללי אבטחה, ביצוע בדיקות יחידות הרבה יותר קלות. בנוסף, הספרייה תומכת בכמה תכונות ספציפיות לאמולטור כמו ניקוי כל הנתונים, כמפורט להלן.
  • האמולטורים יקבלו גם אסימוני ייצור Firebase Auth, המסופקים באמצעות ערכות SDK של לקוחות ויעריכו כללים בהתאם, מה שמאפשר לחבר את היישום שלך ישירות לאמולטורים באינטגרציה ובדיקות ידניות.

הפעל בדיקות יחידה מקומית

הפעל בדיקות יחידה מקומית עם SDK JavaScript v9

Firebase מפיץ ספריית בדיקת יחידות כללי אבטחה עם גרסת 9 JavaScript SDK וגרסה 8 SDK שלה. ממשקי ה- API של הספרייה שונים באופן משמעותי. אנו ממליצים על ספריית הבדיקות v9, שהיא יותר יעילה ודורשת פחות התקנה כדי להתחבר לאמולטורים ובכך להימנע בבטחה משימוש מקרי במשאבי הייצור. לצורך התאימות לאחור, אנחנו ממשיכים לעשות את ספריית בדיקות V8 זמינה .

השתמש @firebase/rules-unit-testing מודול כדי אינטראקציה עם אמולטור כי ריצות מקומית. אם אתה מקבל פסקי זמן או ECONNREFUSED שגיאות, בדוק כי אמולטור פועל למעשה.

אנו ממליצים להשתמש בגירסה האחרונה של Node.js כך שתוכל להשתמש async/await סימון. כמעט כל ההתנהגות שתרצה לבדוק כרוכה בפונקציות אסינכרוניות, ומודול הבדיקה נועד לעבוד עם קוד מבוסס הבטחה.

ספריית בדיקת יחידות v9 Rules מודעת תמיד לאמולטורים ואף פעם לא נוגעת במשאבי הייצור שלך.

אתה מייבא את הספרייה באמצעות הצהרות יבוא מודולריות v9. לדוגמה:

import {
  assertFails,
  assertSucceeds,
  initializeTestEnvironment,
  RulesTestEnvironment,
} from "@firebase/rules-unit-testing"

// Use `const { … } = require("@firebase/rules-unit-testing")` if imports are not supported
// Or we suggest `const testing = require("@firebase/rules-unit-testing")` if necessary.

לאחר ייבוא, יישום בדיקות היחידה כולל:

  • יצירת וקביעת ההגדרות שלה RulesTestEnvironment בקריאה initializeTestEnvironment .
  • הגדרת נתון בדיקה ללא מפעילה חוקית, באמצעות שיטת נוחות המאפשרת לך באופן זמני לעקוף אותם, RulesTestEnvironment.withSecurityRulesDisabled .
  • הגדרת חבילת הבדיקה לכל מבחן לפני / אחרי ווים עם שיחות לנקות נתוני הבדיקה וסביבה, כמו RulesTestEnvironment.cleanup() או RulesTestEnvironment.clearFirestore() .
  • יישום מקרי מבחן שמדינות אימות לחקות באמצעות RulesTestEnvironment.authenticatedContext ו RulesTestEnvironment.unauthenticatedContext .

שיטות נפוצות ופונקציות שירות

ראו גם שיטות בדיקה ספציפי אמולטור ב- SDK v9 .

initializeTestEnvironment() => RulesTestEnvironment

פונקציה זו מאתחלת סביבת בדיקה לבדיקת יחידת כללים. התקשר בפונקציה זו תחילה להגדרת הבדיקה. ביצוע מוצלח דורש הפעלה של אמולטורים.

הפונקציה מקבלת אובייקט אופציונלי הגדרת TestEnvironmentConfig , אשר יכול להכיל זיהה פרויקט אמולטור גדרות תצורה.

let testEnv = await initializeTestEnvironment({
  projectId: "demo-project-1234",
  firestore: {
    rules: fs.readFileSync("firestore.rules", "utf8"),
  },
});

RulesTestEnvironment.authenticatedContext({ user_id: string, tokenOptions?: TokenOptions }) => RulesTestContext

שיטה זו יוצרת RulesTestContext , אשר מתנהג כמו מאומת המשתמשים אימות. לבקשות שנוצרו באמצעות ההקשר המוחזר יצורף אסימון אימות מדומה. לחלופין, העבר אובייקט המגדיר תביעות או דריסות מותאמות אישית עבור מטענים של אסימון אימות.

השתמש אובייקט בהקשר הבדיקה חזיר בבדיקות שלך לגשת לכול מופעים אמולטור המוגדרים, כולל אלה מוגדרים עם initializeTestEnvironment .

// Assuming a Firestore app and the Firestore emulator for this example
import { setDoc } from "firebase/firestore";

const alice = testEnv.authenticatedContext("alice", { … });
// Use the Firestore instance associated with this context
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

RulesTestEnvironment.unauthenticatedContext() => RulesTestContext

שיטה זו יוצרת RulesTestContext , אשר מתנהג כמו לקוח מחובר לא באמצעות אימות. לבקשות שנוצרו באמצעות ההקשר המוחזר לא יהיו מצורפים אסימונים של Firebase Auth.

השתמש אובייקט בהקשר הבדיקה חזיר בבדיקות שלך לגשת לכול מופעים אמולטור המוגדרים, כולל אלה מוגדרים עם initializeTestEnvironment .

// Assuming a Cloud Storage app and the Storage emulator for this example
import { getStorage, ref, deleteObject } from "firebase/storage";

const alice = testEnv.unauthenticatedContext();

// Use the Cloud Storage instance associated with this context
const desertRef = ref(alice.storage(), 'images/desert.jpg');
await assertSucceeds(deleteObject(desertRef));

RulesTestEnvironment.withSecurityRulesDisabled()

הפעל פונקציית התקנת בדיקה עם הקשר המתנהג כאילו כללי האבטחה הושבתו.

שיטה זו לוקחת פונקציית שיחה חוזרת, שלוקחת את ההקשר העוקף כללי אבטחה ומחזירה הבטחה. ההקשר ייהרס ברגע שההבטחה תיפתר / תדחה.

RulesTestEnvironment.cleanup()

שיטה זו הורסת כל RulesTestContexts נוצר בסביבה הבדיקה מנקה את המשאבים הבסיסיים, המאפשר יציאה נקייה.

שיטה זו אינה משנה את מצבם של אמולטורים בשום צורה. כדי לאפס נתונים בין הבדיקות, השתמש בשיטת הנתונים הברורים הספציפיים לאמולטור היישומים.

assertSucceeds(pr: Promise<any>)) => Promise<any>

זוהי פונקציית כלי למבחן.

הפונקציה טוענת כי ההבטחה המסופקת העוטפת פעולת אמולטור תיפתר ללא הפרות של כללי האבטחה.

await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

assertFails(pr: Promise<any>)) => Promise<any>

זוהי פונקציית כלי למבחן.

הפונקציה טוענת כי ההבטחה המסופקת העוטפת פעולת אמולטור תידחה בהפרה של כללי האבטחה.

await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });

שיטות ספציפיות לאמולטור

ראו גם שיטות בדיקה נפוצה ופונקציות שירות ב- SDK v9 .

RulesTestEnvironment.clearFirestore() => Promise<void>

שיטה זו מנקה נתונים במסד הנתונים Firestore ששייך projectId מוגדר עבור אמולטור firestore.

RulesTestContext.firestore(settings?: Firestore.FirestoreSettings) => Firestore;

שיטה זו מקבלת מופע Firestore עבור הקשר הבדיקה הזה. ניתן להשתמש במופע החוזר של Firebase JS Client SDK עם ממשקי ה- API של SDK של הלקוח (תקן v9 מודולרי או תואם v9).

דמיינו הערכות כללים

אמולטור Cloud Firestore מאפשר לך לדמיין בקשות לקוח בממשק המשתמש של Emulator Suite, כולל מעקב אחר הערכה לכללי האבטחה של Firebase.

פתח את הכרטיסייה Firestore> בקשות להציג את רצף הערכה מפורטת לכל בקשה.

מוניטור בקשות אמולטור Firestore שמציג הערכות של כללי אבטחה

צור דוחות בדיקה

לאחר הפעלת חבילת בדיקות, תוכל לגשת לדוחות כיסוי בדיקות המראים כיצד הוערך כללי כללי האבטחה שלך.

כדי לקבל את הדוחות, שאילתה על נקודת קצה חשופה על האמולטור בזמן שהוא פועל. לגרסה ידידותית לדפדפן, השתמש בכתובת האתר הבאה:

http://localhost:8080/emulator/v1/projects/<project_id>:ruleCoverage.html

זה מפר את הכללים שלך לביטויים ולבעיות משנה שתוכל להעביר באמצעות העכבר למידע נוסף, כולל מספר הערכות וערכים שהוחזרו. עבור גרסת JSON הגולמית של נתונים אלה, כלול את כתובת האתר הבאה בשאילתה:

http://localhost:8080/emulator/v1/projects/<project_id>:ruleCoverage

הבדלים בין אמולטור לייצור

  1. אינך צריך ליצור במפורש פרויקט Cloud Firestore. האמולטור יוצר אוטומטית כל מופע שניתן לגשת אליו.
  2. אמולטור Cloud Firestore אינו פועל עם זרימת האימות הרגילה של Firebase. במקום זאת, ב- SDK מבחן Firebase, אנו סיפקו את initializeTestApp() שיטה של rules-unit-testing הספרייה, אשר לוקח auth שדה. ידית Firebase שנוצרה בשיטה זו תתנהג כאילו היא אימתה בהצלחה כל ישות שתספק. אם אתה עובר ב null , זה יתנהג כמו משתמש לא מאומת ( auth != null כללים ייכשלו, למשל).

פתרון בעיות ידועות

בעת השימוש באמולטור Cloud Firestore, אתה עלול להיתקל בבעיות הידועות הבאות. פעל לפי ההנחיות להלן כדי לפתור בעיות בהתנהגות לא סדירה שאתה חווה. הערות אלה נכתבות מתוך מחשבה על ספריית הבדיקה של כללי האבטחה, אך הגישות הכלליות ישימות לכל SDK של Firebase.

התנהגות הבדיקה אינה עקבית

אם הבדיקות שלך חולפות מדי פעם ונכשלות, אפילו ללא כל שינוי בבדיקות עצמן, ייתכן שיהיה עליך לוודא שהן רצופות כראוי. רוב האינטראקציות עם האימולטור הן אסינכרוניות, לכן בדוק שוב שכל הקוד האסינכרוני ברצף כהלכה. אתה יכול לתקן את הרצף בין אם על ידי שרשור הבטחות, או באמצעות await בסימון בנדיבות.

בפרט, בדוק את פעולות האסינכרון הבאות:

  • הגדרת כללי אבטחה, עם, למשל, initializeTestEnvironment .
  • קריאה וכתיבה של נתונים, עם, למשל, db.collection("users").doc("alice").get() .
  • טענות תפעוליות, כולל assertSucceeds ו assertFails .

הבדיקות עוברות רק בפעם הראשונה שאתה טוען את האמולטור

האמולטור הוא סטטוס. הוא מאחסן את כל הנתונים שנכתבו לו בזיכרון, כך שכל הנתונים הולכים לאיבוד בכל פעם שהאמולטור נכבה. אם אתה מריץ מספר בדיקות מול אותו מזהה פרוייקט, כל בדיקה יכולה לייצר נתונים שעשויים להשפיע על הבדיקות הבאות. אתה יכול להשתמש בכל אחת מהשיטות הבאות כדי לעקוף התנהגות זו:

  • השתמש במזהי פרויקטים ייחודיים לכל בדיקה. שים לב שאם אתה בוחר לעשות זאת תצטרך לקרוא initializeTestEnvironment כחלק כל בדיקה; כללים נטענים רק באופן אוטומטי עבור מזהה הפרויקט המוגדר כברירת מחדל.
  • בנה מחדש את הבדיקות שלך כך שלא יתקיימו אינטראקציה עם נתונים שנכתבו בעבר (לדוגמה, השתמש באוסף אחר עבור כל בדיקה).
  • מחק את כל הנתונים שנכתבו במהלך בדיקה.

התקנת הבדיקה מסובכת מאוד

בעת הגדרת הבדיקה, ייתכן שתרצה לשנות נתונים באופן שכללי האבטחה שלך ב- Cloud Firestore אינם מאפשרים בפועל. אם הכללים שלך עושים בדיקה מורכבת התקנה, נסה להשתמש RulesTestEnvironment.withSecurityRulesDisabled בצעדים בהגדרות השרת ולכן קריאה וכתיבה לא תפעיל PERMISSION_DENIED שגיאות.

אחרי זה, המבחן שלך יכול לבצע פעולות כמו משתמש מאומת או לא מאומת באמצעות RulesTestEnvironment.authenticatedContext ו unauthenticatedContext בהתאמה. זה מאפשר לך לאמת שכללי האבטחה שלך ב- Cloud Firestore מאפשרים / מכחישים מקרים שונים בצורה נכונה.