מבנה של כללי אבטחה ב-Cloud Firestore

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

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

הערה: ספריות הלקוח של השרת עוקפות את כל הפעולות Cloud Firestore Security Rules ובמקום זאת לבצע אימות באמצעות ברירת המחדל של פרטי הכניסה לאפליקציות Google. אם אתם משתמשים בספריות הלקוח של השרת או בממשקי ה-API ל-REST או ל-RPC, צריך לוודא כדי להגדיר ניהול זהויות והרשאות גישה (IAM) ב-Cloud Firestore.

הצהרה על שירות ומסד נתונים

Cloud Firestore Security Rules תמיד מתחיל בהצהרה הבאה:

service cloud.firestore {
  match /databases/{database}/documents {
    // ...
  }
}

ההצהרה service cloud.firestore כוללת את הכללים הבאים Cloud Firestore, במניעת התנגשויות בין Cloud Firestore Security Rules לבין למוצרים אחרים כמו Cloud Storage.

בהצהרה match /databases/{database}/documents מצוין שהכללים צריכים להתאים לכל מסד נתונים מסוג Cloud Firestore בפרויקט. כרגע כל פרויקט יש רק מסד נתונים אחד בשם (default).

כללי קריאה/כתיבה בסיסיים

כללים בסיסיים מורכבים מהצהרת match שמציינת נתיב למסמך מותר להשתמש בביטוי allow המפרט במהלך קריאת הנתונים שצוינו:

service cloud.firestore {
  match /databases/{database}/documents {

    // Match any document in the 'cities' collection
    match /cities/{city} {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

כל הצהרות ההתאמה צריכות להפנות למסמכים, לא לאוספים. התאמה ההצהרה יכולה להפנות למסמך ספציפי, כמו match /cities/SF, או להשתמש בתווים כלליים לחיפוש כדי להצביע על מסמך כלשהו בנתיב שצוין, כמו ב-match /cities/{city}.

בדוגמה שלמעלה, הצהרת ההתאמה משתמשת בתחביר של התו הכללי לחיפוש {city}. המשמעות היא שהכלל חל על כל מסמך באוסף cities, כמו /cities/SF או /cities/NYC. כאשר הביטויים allow בהצהרת ההתאמה הם הווריאנט city יקבל את שם המסמך של העיר, כמו SF או NYC.

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

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

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

אפשר לפצל כלל read ל-get ול-list, ואפשר לפצל כלל write ל-create, ל-update ול-delete:

service cloud.firestore {
  match /databases/{database}/documents {
    // A read rule can be divided into get and list rules
    match /cities/{city} {
      // Applies to single document read requests
      allow get: if <condition>;

      // Applies to queries and collection read requests
      allow list: if <condition>;
    }

    // A write rule can be divided into create, update, and delete rules
    match /cities/{city} {
      // Applies to writes to nonexistent documents
      allow create: if <condition>;

      // Applies to writes to existing documents
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
}

נתונים היררכיים

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

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

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      allow read, write: if <condition>;

        // Explicitly define rules for the 'landmarks' subcollection
        match /landmarks/{landmark} {
          allow read, write: if <condition>;
        }
    }
  }
}

כשמציבים הצהרות match בתוך הצהרה, הנתיב של ההצהרה match הפנימית הוא תמיד ביחס לנתיב של ההצהרה החיצונית match. לכן, כללי המדיניות הבאים זהים:

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      match /landmarks/{landmark} {
        allow read, write: if <condition>;
      }
    }
  }
}

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city}/landmarks/{landmark} {
      allow read, write: if <condition>;
    }
  }
}

תווים כלליים לחיפוש רקורסיבי

אם רוצים שהכללים יחולו על היררכיה עמוקה ושרירותית, אפשר להשתמש תחביר של תווים כלליים לחיפוש רקורסיבי, {name=**}. לדוגמה:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

כשמשתמשים בתחביר של תו כללי לחיפוש רקורסיבי, משתנה התו הכללי לחיפוש יכיל את התחילית כל קטע הנתיב התואם, גם אם המסמך ממוקם בתוך קטע עמוק יותר תת-אוסף. לדוגמה, הכללים שמפורטים למעלה יתאימו למסמך שנמצא בכתובת /cities/SF/landmarks/coit_tower, והערך של המשתנה document יהיה SF/landmarks/coit_tower.

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

גרסה 1

כברירת מחדל, כללי האבטחה משתמשים בגרסה 1. בגרסה 1, תווים כלליים לחיפוש רקורסיביים תואם לפריט נתיב אחד או יותר. הם לא תואמים לנתיב ריק, לכן match /cities/{city}/{document=**} תואם למסמכים באוספי משנה, אבל לא באוסף cities, ואילו match /cities/{document=**} התאמות בשני המסמכים באוסף cities וגם באוספי המשנה.

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

גרסה 2

בגרסה 2 של כללי האבטחה, תווים כלליים לחיפוש רקורסיביים תואמים לאפס נתיב או יותר פריטים. match/cities/{city}/{document=**} תואם למסמכים בכל ואוספים נוספים וכן מסמכים באוסף cities.

צריך להצטרף לגרסה 2. לשם כך, מוסיפים את rules_version = '2'; בחלק העליון של כללי האבטחה שלך:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{city}/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

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

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the songs collection group
    match /{path=**}/songs/{song} {
      allow read, write: if <condition>;
    }
  }
}

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

הצהרות התאמה חופפות

מסמך יכול להתאים ליותר מהצהרה אחת ב-match. במקרה שבו כמה ביטויים של allow תואמים לבקשה, הגישה מותרת אם אחד מהתנאים הוא true:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the 'cities' collection.
    match /cities/{city} {
      allow read, write: if false;
    }

    // Matches any document in the 'cities' collection or subcollections.
    match /cities/{document=**} {
      allow read, write: if true;
    }
  }
}

בדוגמה שלמעלה, כל הקריאות והכתובות לאוסף cities יהיו מותרות כי הכלל השני הוא תמיד true, גם אם הכלל הראשון הוא תמיד false.

מגבלות על כללי אבטחה

כשאתם עובדים עם כללי אבטחה, שימו לב למגבלות הבאות:

הגבלה	פרטים
מספר מקסימלי של exists(), get() ו-getAfter() שיחות לכל בקשה	10 לבקשות של מסמך יחיד ולבקשות של שאילתות. 20 לקריאות, טרנזקציות של מסמכים מרובים וכתיבה באצווה. המגבלה הקודמת של 10 חלה גם על כל אחד מהם פעולה. לדוגמה, נניח שיצרתם בקשת כתיבה באצווה עם 3 פעולות כתיבה, ושכללי האבטחה שלכם משתמשים ב-2 קריאות גישה למסמך כדי לאמת כל פעולת כתיבה. במקרה כזה, כל פעולת כתיבה משתמשת ב-2 מתוך 10 קריאות הגישה שלה, ובבקשת הכתיבה בכמות גדולה משתמשים ב-6 מתוך 20 קריאות הגישה שלה. אם חורגים מאחד מהגבולות האלה, מתקבלת הודעת שגיאה מסוג 'הרשאה נדחתה'. ייתכן שחלק מהקריאות לגישה למסמכים יישמרו במטמון, ושיחות שנשמרו במטמון לא נכללות בחישוב של המגבלות.
עומק הקינון המקסימלי של משפטי match	10
אורך הנתיב המקסימלי, בקטעי נתיב, שמותר בתוך קבוצה של משפטי match בתצוגת עץ	100
המספר המקסימלי של משתני תיעוד נתיב שמותר להשתמש בהם בתוך קבוצה של משפטי match בתצוגת עץ	20
עומק הקריאה המקסימלי של פונקציה	20
מספר הארגומנטים המקסימלי של פונקציה	7
המספר המקסימלי של קישורי משתני let לכל פונקציה	10
המספר המקסימלי של הפעלות של פונקציות רקורסיביות או מחזוריות	0 (לא אפשרי)
המספר המקסימלי של ביטויים שאפשר להעריך בכל בקשה	1,000
גודל מקסימלי של קבוצת כללים	קבוצות כללים חייבות לציית לשתי מגבלות גודל: מגבלה של 256KB על גודל מקור הטקסט של כללי המדיניות שפורסם מהמסוף Firebase או מה-CLI באמצעות firebase deploy. מגבלה של 250KB על הגודל של קבוצת הכללים המורכבת שמובילה כשמערכת Firebase מעבדת את המקור והופכת אותו לפעיל בקצה העורפי.

השלבים הבאים

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