安全性規則的運作方式

Cloud Firestore

基本結構

Cloud Firestore 和 Cloud Storage 中的 Firebase Security Rules 採用以下結構和 語法：

service <<name>> {
  // Match the resource path.
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}

建立規則時，請務必瞭解以下重要概念：

• 要求：allow 陳述式中叫用的方法或方法。這些 您允許執行的方法標準方法包括：get、list、 create、update和delete。read 和 write 便利方法 對指定的資料庫或儲存空間路徑啟用廣泛的讀寫存取權。
• 路徑：資料庫或儲存空間位置，以 URI 路徑。
• 規則：allow 陳述式，其中包含允許 傳回的結果。

安全性規則第 2 版

自 2019 年 5 月起，Firebase 安全性規則的第 2 版現已上線 廣告。規則第 2 版改變了遞迴性 萬用字元 {name=**}。如果您打算使用第 2 版 使用集合群組查詢。您必須選擇加入 版本 2，確保安全性的第一行 rules_version = '2'; 規則：

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

比對路徑

所有比對陳述式都應指向文件，而非集合。配對 陳述式可以指向特定文件 (例如 match /cities/SF)，或使用萬用字元 指向指定路徑中的任何文件，如 match /cities/{city} 中所示。

在上述範例中，比對陳述式使用 {city} 萬用字元語法。 也就是說，這項規則適用於 cities 集合中的任何文件，例如 /cities/SF 或 /cities/NYC。當比對陳述式中的 allow 運算式出現 city 變數會解析為城市文件名稱。 例如 SF 或 NYC

相符的子集合

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。

不過請注意，遞迴萬用字元的行為取決於規則 版本。

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>;
    }
  }
}

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>;
    }
  }
}

如果您使用集合群組查詢，請務必使用 請參閱「保護集合群組查詢」一節。

重疊的比對聲明

文件可能會比對多個 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，但第 1 項 則一律為 false。

安全性規則限制

處理安全性規則時，請注意以下限制：

Cloud Storage

基本結構

Cloud Firestore 和 Cloud Storage 中的 Firebase Security Rules 採用以下結構和 語法：

service <<name>> {
  // Match the resource path.
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}

建立規則時，請務必瞭解以下重要概念：

• 要求：allow 陳述式中叫用的方法或方法。這些 您允許執行的方法標準方法包括：get、list、 create、update和delete。read 和 write 便利方法 對指定的資料庫或儲存空間路徑啟用廣泛的讀寫存取權。
• 路徑：資料庫或儲存空間位置，以 URI 路徑。
• 規則：allow 陳述式，其中包含允許 傳回的結果。

比對路徑

Cloud Storage Security Rules match存取用來存取檔案的檔案路徑 Cloud Storage。規則可以match確切路徑或萬用字元路徑，以及 也可以建立巢狀結構如果沒有比對規則允許要求方法，或 條件評估為 false，系統就會拒絕要求。

完全相符的結果

// Exact match for "images/profilePhoto.png"
match /images/profilePhoto.png {
  allow write: if <condition>;
}

// Exact match for "images/croppedProfilePhoto.png"
match /images/croppedProfilePhoto.png {
  allow write: if <other_condition>;
}

巢狀比對

// Partial match for files that start with "images"
match /images {
  // Exact match for "images/profilePhoto.png"
  match /profilePhoto.png {
    allow write: if <condition>;
  }

  // Exact match for "images/croppedProfilePhoto.png"
  match /croppedProfilePhoto.png {
    allow write: if <other_condition>;
  }
}

萬用字元比對

規則也可以使用萬用字元來 match 模式。萬用字元是 具名變數，代表單一字串，例如 profilePhoto.png，或是多個路徑區隔，例如 images/profilePhoto.png。

建立萬用字元的方法是在萬用字元名稱前後加上大括號，例如： {string}。如要宣告多個片段萬用字元，請在=** 萬用字元名稱，例如 {path=**}：

// Partial match for files that start with "images"
match /images {
  // Exact match for "images/*"
  // e.g. images/profilePhoto.png is matched
  match /{imageId} {
    // This rule only matches a single path segment (*)
    // imageId is a string that contains the specific segment matched
    allow read: if <condition>;
  }

  // Exact match for "images/**"
  // e.g. images/users/user:12345/profilePhoto.png is matched
  // images/profilePhoto.png is also matched!
  match /{allImages=**} {
    // This rule matches one or more path segments (**)
    // allImages is a path that contains all segments matched
    allow read: if <other_condition>;
  }
}

如果有多個規則與檔案相符，結果會是所有結果的 OR 評估規則也就是說，如果檔案符合的任何規則評估為 true， 結果是 true。

在上述規則中，檔案「images/profilePhoto.png」就能讀取 condition 或 other_condition 的值為 true，而檔案 「images/users/user:12345/profilePhoto.png」只有在結果為 other_condition。

您可以在 match 提供檔案中參照萬用字元變數 名稱或路徑授權：

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

Cloud Storage Security Rules 不會串聯，且系統只會評估 要求路徑與包含指定規則的路徑相符。

要求評估

上傳、下載、中繼資料變更和刪除等作業， request已匯款給 Cloud Storage。request 變數包含 執行要求的檔案路徑、要求執行要求的時間 如果要求是寫入，則新的 resource 值。HTTP 標頭 以及驗證狀態

request 物件也會包含使用者的專屬 ID，以及 request.auth 物件中的 Firebase Authentication 酬載， 如要進一步瞭解，請參閱驗證 一節。

以下是 request 物件中的完整屬性清單：

資源評估

評估規則時，建議您評估檔案的中繼資料 上傳、下載、修改或刪除這可讓您 複雜且功能強大的規則，例如僅允許符合特定條件的檔案 要上傳的內容類型，或只上傳大於特定大小的檔案 已刪除。

Cloud Storage 的 Firebase Security Rules 提供 resource 中的檔案中繼資料 物件，其中包含出現在 Cloud Storage 物件。如要查看這些屬性，請前往 read 或 用於確保資料完整性的 write 要求。

針對 write 要求 (例如上傳、中繼資料更新與刪除)， 以及 resource 物件，其中包含檔案的檔案中繼資料 目前存在於要求路徑上 的物件，您也可以使用 request.resource 物件，其中包含要匯入的檔案中繼資料子集 但若允許寫入。您可以運用這兩個值來確保 完整性或強制執行應用程式限制，例如檔案類型或大小。

以下是 resource 物件中的完整屬性清單：

request.resource 包含以上所有項目，但 generation 除外。 metageneration、etag、timeCreated和updated。

安全性規則限制

處理安全性規則時，請注意以下限制：

完整範例

總結來說，您可以建立完整的圖片規則範例 儲存空間解決方案：

service firebase.storage {
 match /b/{bucket}/o {
   match /images {
     // Cascade read to any image type at any path
     match /{allImages=**} {
       allow read;
     }

     // Allow write files to the path "images/*", subject to the constraints:
     // 1) File is less than 5MB
     // 2) Content type is an image
     // 3) Uploaded content type matches existing content type
     // 4) File name (stored in imageId wildcard variable) is less than 32 characters
     match /{imageId} {
       allow write: if request.resource.size < 5 * 1024 * 1024
                    && request.resource.contentType.matches('image/.*')
                    && request.resource.contentType == resource.contentType
                    && imageId.size() < 32
     }
   }
 }
}

Realtime Database

基本結構

在 Realtime Database 中，Firebase Security Rules 包含類似 JavaScript 的運算式，包含在 JSON 文件。

它們的語法如下：

{
  "rules": {
    "<<path>>": {
    // Allow the request if the condition for each method is true.
      ".read": <<condition>>,
      ".write": <<condition>>,
      ".validate": <<condition>>
    }
  }
}

規則包含三個基本元素：

• 路徑：資料庫位置。這會反映資料庫的 JSON 結構。
• 要求：以下是規則用來授予存取權的方法。read 和 write 規則授予廣泛的讀取和寫入權限，validate 規則則授予 做為次要驗證方式，根據傳入或現有的資料來授予存取權 資料。
• 條件：允許要求在評估為 true 時允許的條件。

規則套用到路徑的方式

在 Realtime Database 中，Rules 會以不可分割的形式套用，亦即位於 較高層級的父項節點會覆寫規則 更精細的子節點 較深節點的規則無法授予父項路徑的存取權。個人中心 無法修正或撤銷資料庫結構中更深層的存取權 您已經為其中一個父項路徑授予這個角色。

請參考下列規則：

{
  "rules": {
     "foo": {
        // allows read to /foo/*
        ".read": "data.child('baz').val() === true",
        "bar": {
          // ignored, since read was allowed already
          ".read": false
        }
     }
  }
}

這個安全性結構允許 /bar/ 讀取 /foo/ 包含具有 true 值的子項 baz。 /foo/bar/ 下的 ".read": false 規則沒有任何 因為子項路徑無法撤銷存取權。

雖然您不一定要提供直覺易用的功能，但這項重要功能是 允許實施非常複雜的存取權限 以最省力的方式執行這對以使用者為基礎的安全機制來說特別實用。

不過，.validate 規則不會串聯。所有驗證規則 都必須滿足階層的所有層級要求，才能允許寫入。

此外，由於規則不會套用到父項路徑，因此讀取或寫入 作業失敗時，如果沒有指定位置或父項規則 授予存取權限的位置即使每個受影響的子項路徑都可以存取 導致無法完整讀取請參考以下結構：

{
  "rules": {
    "records": {
      "rec1": {
        ".read": true
      },
      "rec2": {
        ".read": false
      }
    }
  }
}

如果不瞭解規則會以不可分割的形式進行評估 擷取 /records/ 路徑時，將傳回 rec1 但不含 rec2。不過，實際結果會是錯誤：

var db = firebase.database();
db.ref("records").once("value", function(snap) {
  // success method is not called
}, function(err) {
  // error callback triggered with PERMISSION_DENIED
});

FIRDatabaseReference *ref = [[FIRDatabase database] reference];
[[_ref child:@"records"] observeSingleEventOfType:FIRDataEventTypeValue withBlock:^(FIRDataSnapshot *snapshot) {
  // success block is not called
} withCancelBlock:^(NSError * _Nonnull error) {
  // cancel block triggered with PERMISSION_DENIED
}];

var ref = FIRDatabase.database().reference()
ref.child("records").observeSingleEventOfType(.Value, withBlock: { snapshot in
    // success block is not called
}, withCancelBlock: { error in
    // cancel block triggered with PERMISSION_DENIED
})

FirebaseDatabase database = FirebaseDatabase.getInstance();
DatabaseReference ref = database.getReference("records");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
  @Override
  public void onDataChange(DataSnapshot snapshot) {
    // success method is not called
  }

  @Override
  public void onCancelled(FirebaseError firebaseError) {
    // error callback triggered with PERMISSION_DENIED
  });
});

curl https://docs-examples.firebaseio.com/rest/records/
# response returns a PERMISSION_DENIED error

由於 /records/ 的讀取作業不可部分完成，而且沒有讀取規則授予 /records/ 下所有資料的存取權，因此系統會擲回 PERMISSION_DENIED 錯誤。如果我們透過 Firebase 控制台的安全模擬工具評估這項規則，可以發現讀取作業遭到拒絕：

Attempt to read /records with auth=Success(null)
    /
    /records

No .read rule allowed the operation.
Read was denied.

沒有任何讀取規則允許存取 /records/ 路徑，因此作業遭拒。請注意，系統並未評估 rec1 的規則，因為該規則不在我們要求的路徑中。如要擷取 rec1，我們必須直接存取：

var db = firebase.database();
db.ref("records/rec1").once("value", function(snap) {
  // SUCCESS!
}, function(err) {
  // error callback is not called
});

FIRDatabaseReference *ref = [[FIRDatabase database] reference];
[[ref child:@"records/rec1"] observeSingleEventOfType:FEventTypeValue withBlock:^(FIRDataSnapshot *snapshot) {
    // SUCCESS!
}];

var ref = FIRDatabase.database().reference()
ref.child("records/rec1").observeSingleEventOfType(.Value, withBlock: { snapshot in
    // SUCCESS!
})

FirebaseDatabase database = FirebaseDatabase.getInstance();
DatabaseReference ref = database.getReference("records/rec1");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
  @Override
  public void onDataChange(DataSnapshot snapshot) {
    // SUCCESS!
  }

  @Override
  public void onCancelled(FirebaseError firebaseError) {
    // error callback is not called
  }
});

curl https://docs-examples.firebaseio.com/rest/records/rec1
# SUCCESS!

位置變數

Realtime Database Rules支援 $location 來比對路徑區隔在路徑前方使用 $ 前置字串 來比對規則和路徑上所有的子節點

  {
    "rules": {
      "rooms": {
        // This rule applies to any child of /rooms/, the key for each room id
        // is stored inside $room_id variable for reference
        "$room_id": {
          "topic": {
            // The room's topic can be changed if the room id has "public" in it
            ".write": "$room_id.contains('public')"
          }
        }
      }
    }
  }

您也可以使用 $variable 搭配常數路徑 。

  {
    "rules": {
      "widget": {
        // a widget can have a title or color attribute
        "title": { ".validate": true },
        "color": { ".validate": true },

        // but no other child paths are allowed
        // in this case, $other means any key excluding "title" and "color"
        "$other": { ".validate": false }
      }
    }
  }