Cấu trúc các quy tắc bảo mật của Cloud Firestore

Cloud Firestore Security Rules cho phép bạn kiểm soát quyền truy cập vào tài liệu và tập hợp trong cơ sở dữ liệu của mình. Cú pháp quy tắc linh hoạt cho phép bạn tạo các quy tắc phù hợp với mọi thứ, từ tất cả các hoạt động ghi vào toàn bộ cơ sở dữ liệu cho đến các thao tác trên một tài liệu cụ thể.

Hướng dẫn này mô tả cú pháp và cấu trúc cơ bản của quy tắc bảo mật. Kết hợp cú pháp này với các điều kiện của quy tắc bảo mật để tạo ra các bộ quy tắc hoàn chỉnh.

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Firestore data.

Khai báo dịch vụ và cơ sở dữ liệu

Cloud Firestore Security Rules luôn bắt đầu bằng nội dung khai báo sau:

service cloud.firestore {
  // The {database} wildcard allows the rules to reference any database,
  // but these rules are only active on databases where they are explicitly deployed.
  match /databases/{database}/documents {
    // ...
  }
}

Nội dung khai báo service cloud.firestore sẽ đặt phạm vi cho các quy tắc thành Rules, ngăn chặn xung đột giữa Cloud Firestore Security Rules và các quy tắc cho những sản phẩm khác như Cloud Storage.

Khai báo match /databases/{database}/documents chỉ định rằng các quy tắc phải khớp với bất kỳ cơ sở dữ liệu Quy tắc nào trong dự án. Mặc dù một dự án có thể chứa tối đa 100 cơ sở dữ liệu, nhưng chỉ cơ sở dữ liệu đầu tiên được tạo mới được chỉ định làm cơ sở dữ liệu mặc định.

Cloud Firestore Security Rules được áp dụng riêng cho từng cơ sở dữ liệu có tên trong dự án của bạn. Điều này có nghĩa là nếu tạo nhiều cơ sở dữ liệu, bạn phải quản lý và triển khai các quy tắc cho từng cơ sở dữ liệu riêng biệt. Để biết hướng dẫn chi tiết về cách triển khai bản cập nhật, hãy xem phần Triển khai bản cập nhật.

Quy tắc đọc/ghi cơ bản

Các quy tắc cơ bản bao gồm một câu lệnh match chỉ định đường dẫn tài liệu và một biểu thức allow nêu chi tiết thời điểm được phép đọc dữ liệu đã chỉ định:

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

Tất cả câu lệnh khớp phải trỏ đến tài liệu, không phải tập hợp. Câu lệnh match có thể trỏ đến một tài liệu cụ thể, như trong match /cities/SF hoặc sử dụng ký tự đại diện để trỏ đến bất kỳ tài liệu nào trong đường dẫn đã chỉ định, như trong match /cities/{city}.

Trong ví dụ trên, câu lệnh khớp sử dụng cú pháp ký tự đại diện {city}. Điều này có nghĩa là quy tắc này áp dụng cho mọi tài liệu trong tập hợp cities, chẳng hạn như /cities/SF hoặc /cities/NYC. Khi các biểu thức allow trong câu lệnh khớp được đánh giá, biến city sẽ phân giải thành tên tài liệu thành phố, chẳng hạn như SF hoặc NYC.

Thao tác chi tiết

Trong một số trường hợp, bạn nên chia nhỏ read và write thành các thao tác chi tiết hơn. Ví dụ: ứng dụng của bạn có thể muốn thực thi các điều kiện khác nhau khi tạo tài liệu so với khi xoá tài liệu. Hoặc bạn có thể muốn cho phép đọc một tài liệu nhưng từ chối các truy vấn lớn.

Quy tắc read có thể được chia thành get và list, trong khi quy tắc write có thể được chia thành create, update và 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>;
    }
  }
}

Dữ liệu phân cấp

Dữ liệu trong Quy tắc được sắp xếp thành các tập hợp tài liệu và mỗi tài liệu có thể mở rộng hệ phân cấp thông qua các tập hợp con. Điều quan trọng là bạn phải hiểu cách các quy tắc bảo mật tương tác với dữ liệu phân cấp.

Hãy xem xét trường hợp mỗi tài liệu trong tập hợp cities chứa một tập hợp con landmarks. Quy tắc bảo mật chỉ áp dụng tại đường dẫn khớp, vì vậy, các chế độ kiểm soát quyền truy cập được xác định trên tập hợp cities không áp dụng cho tập hợp con landmarks. Thay vào đó, hãy viết các quy tắc rõ ràng để kiểm soát quyền truy cập vào các tập hợp con:

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

Khi lồng các câu lệnh match, đường dẫn của câu lệnh match bên trong luôn tương ứng với đường dẫn của câu lệnh match bên ngoài. Do đó, các bộ quy tắc sau đây là tương đương:

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

Ký tự đại diện đệ quy

Nếu bạn muốn áp dụng quy tắc cho một hệ phân cấp sâu tuỳ ý, hãy sử dụng cú pháp ký tự đại diện đệ quy, {name=**}. Ví dụ:

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

Khi sử dụng cú pháp ký tự đại diện đệ quy, biến ký tự đại diện sẽ chứa toàn bộ phân đoạn đường dẫn trùng khớp, ngay cả khi tài liệu nằm trong một tập hợp con lồng nhau sâu. Ví dụ: các quy tắc nêu trên sẽ khớp với một tài liệu tại /cities/SF/landmarks/coit_tower và giá trị của biến document sẽ là SF/landmarks/coit_tower.

Tuy nhiên, xin lưu ý rằng hành vi của ký tự đại diện đệ quy phụ thuộc vào phiên bản quy tắc.

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

Nếu sử dụng truy vấn nhóm tập hợp, bạn phải sử dụng phiên bản 2, hãy xem phần bảo mật truy vấn nhóm tập hợp.

Thông báo về nội dung trùng khớp chồng chéo

Một tài liệu có thể khớp với nhiều câu lệnh match. Trong trường hợp có nhiều biểu thức allow khớp với một yêu cầu, quyền truy cập sẽ được cấp nếu bất kỳ điều kiện nào là 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;
    }
  }
}

Trong ví dụ trên, tất cả các thao tác đọc và ghi vào tập hợp cities đều được cho phép vì quy tắc thứ hai luôn là true, mặc dù quy tắc đầu tiên luôn là false.

Giới hạn về quy tắc bảo mật

Khi bạn làm việc với các quy tắc bảo mật, hãy lưu ý các giới hạn sau:

Các bước tiếp theo

• Viết điều kiện quy tắc bảo mật tuỳ chỉnh.
• Đọc tài liệu tham khảo về quy tắc bảo mật.