شروع به کار با Cloud Firestore Security Rules

با Cloud Firestore Security Rules، می‌توانید بدون نیاز به مدیریت زیرساخت یا نوشتن کد اصالت‌سنجی و مجوز سمت سرور، بر ساختن تجربه کاربری عالی تمرکز کنید.

قوانین امنیتی کنترل دسترسی و اعتبارسنجی داده‌ها را در قالبی ساده و درعین‌حال گویا ارائه می‌دهند. برای ساختن سیستم‌های دسترسی مبتنی بر کاربر و مبتنی بر نقش که داده‌های کاربران را ایمن نگه می‌دارد، باید از اصالت‌سنجی Firebase با Cloud Firestore Security Rules استفاده کنید.





برای کمک هوش مصنوعی، پیام‌واره زیر را در عامل کدنویسی هوش مصنوعی خود (مانند Gemini در Android Studio،‏ Antigravity،‏ Claude Code،‏ Codex، و Cursor) کپی کنید. می‌توانید پیام‌واره را سفارشی‌سازی کنید و با نماینده‌تان تکرار کنید. برای اطلاعات دقیق نصب، به مهارت‌های عامل Firebase مراجعه کنید. 

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.

قوانین امنیتی نسخه ۲

از مه ۲۰۱۹، نسخه ۲ قوانین امنیتی Cloud Firestore اکنون دردسترس است. نسخه ۲ قوانین، رفتار جای‌بان‌های بازگشتی {name=**} را تغییر می‌دهد. اگر قصد دارید از پرس‌وجوهای گروه مجموعه استفاده کنید، باید از نسخه ۲ استفاده کنید. باید با قرار دادن rules_version = '2'; در خط اول قوانین امنیتی‌تان، با نسخه ۲ موافقت کنید:

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

قوانین نوشتن

Cloud Firestore Security Rules را متناسب با مدل داده‌ای که برای پایگاه داده پیش‌فرض و هر پایگاه داده اضافی در پروژه‌تان ایجاد می‌کنید، خواهید نوشت و مدیریت خواهید کرد.

همه Cloud Firestore Security Rules از عبارت‌های match تشکیل شده‌اند که اسناد را در پایگاه داده شما شناسایی می‌کنند، و عبارت‌های allow که دسترسی به آن اسناد را کنترل می‌کنند:

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

هر درخواست پایگاه داده از کتابخانه کارخواه وب/تلفن همراه Cloud Firestore قبل‌از خواندن یا نوشتن هرگونه داده، براساس قوانین امنیتی شما ارزیابی می‌شود. اگر قوانین دسترسی به هرکدام از مسیرهای سند مشخص‌شده را رد کند، کل درخواست ناموفق می‌شود.

در زیر چند نمونه از مجموعه‌های قانون پایه آورده شده است. اگرچه این قوانین معتبر هستند، برای برنامه‌های تولید توصیه نمی‌شوند:

احراز هویت لازم است

// Allow read/write access on all documents to any user signed in to the application
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if request.auth != null;
    }
  }
}

نپذیرفتن همه

// Deny read/write access to all users under any conditions
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

اجازه دادن همه

// Allow read/write access to all users under any conditions
// Warning: **NEVER** use this rule set in production; it allows
// anyone to overwrite your entire database.
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if true;
    }
  }
}

مسیر {document=**} که در مثال‌های بالا استفاده شده است با هر سندی در کل پایگاه داده مطابقت دارد. برای آشنایی با نحوه مطابقت دادن مسیرهای داده خاص و کار با داده‌های سلسله‌مراتبی، به راهنمای ساختاردهی به قوانین امنیتی بروید.

قوانین آزمایش

Cloud Firestore شبیه‌ساز قوانینی ارائه می‌دهد که می‌توانید از آن برای آزمایش کردن مجموعه قوانینتان استفاده کنید. می‌توانید هم در کنسول Google Cloud و هم در کنسول Firebase به شبیه‌ساز دسترسی داشته باشید.

شبیه‌ساز قوانین به شما امکان می‌دهد خواندن، نوشتن، و حذف کردن اصالت‌سنجی‌شده و اصالت‌سنجی‌نشده را شبیه‌سازی کنید. وقتی درخواست اصالت‌سنجی‌شده را شبیه‌سازی می‌کنید، می‌توانید نشان‌های اصالت‌سنجی را از ارائه‌دهندگان مختلف بسازید و پیش‌نمایش کنید. درخواست‌های شبیه‌سازی‌شده دربرابر مجموعه قوانین در ویرایشگر شما اجرا می‌شوند، نه مجموعه قوانین مستقرشده شما.

آزمایش کردن قوانین در کنسول Google Cloud

شبیه‌ساز قوانین در کنسول Google Cloud برای Firestore در حالت «بومی» در هر دو نسخه Standard و Enterprise دردسترس است.

مجوزهای لازم

برای آزمایش قوانین امنیتی در کنسول Google Cloud، به اجازه IAM زیر نیاز دارید:

  • firebaserules.rulesets.test

برای شبیه‌سازی کردن درخواست پایگاه داده در کنسول Google Cloud:

  1. در کنسول Google Cloud، به صفحه پایگاه‌های داده بروید.
  2. روی شناسه پایگاه داده‌ای که می‌خواهید آزمایش کنید کلیک کنید.
  3. در منوِ پیمایش، روی امنیت کلیک کنید.
  4. روی برگه شبیه‌ساز کلیک کنید.
  5. در فهرست کرکره‌ای نوع شبیه‌سازی، نوع عملیات را انتخاب کنید: دریافت، ایجاد، به‌روزرسانی، یا حذف.
  6. در فیلد مکان، مسیر سندی را که می‌خواهید آزمایش کنید وارد کنید (برای مثال، users/user_123).
  7. (اختیاری) برای درخواست‌های ایجاد و به‌روزرسانی، روی ساختن سند کلیک کنید تا بار داده سند ساختگی را پیکربندی کنید.
  8. (اختیاری) برای شبیه‌سازی درخواست اصالت‌سنجی‌شده، اصالت‌سنجی را روشن کنید، ارائه‌دهنده اصالت‌سنجی (مانند google.com یا ناشناس) را انتخاب کنید، و فیلدهای بار داده کد را پیکربندی کنید.
  9. روی اجرا کلیک کنید.

پانل ارزیابی نشان می‌دهد که درخواست مجاز بوده است یا رد شده است، موارد گزارش تفصیلی برای هر شرط ارزیابی‌شده، و موارد برجسته سطح خط در ویرایشگر کد.

آزمایش کردن قوانین در کنسول Firebase

برای آزمایش کردن قوانین در کنسول Firebase، به برگه پایگاه‌های داده و فضای ذخیره‌سازی > Firestore > قوانین بروید. روی محیط آزمایشی قوانین کلیک کنید تا تنظیمات شبیه‌ساز باز شود، گزینه‌های شبیه‌سازی را انتخاب کنید، و سپس روی اجرا کلیک کنید.

درحال استقرار قوانین

قبل‌از اینکه بتوانید از Cloud Firestore در برنامه تلفن همراهتان استفاده کنید، باید قوانین امنیتی را مستقر کنید. می‌توانید قوانین را در کنسول Firebase، در کنسول Google Cloud، بااستفاده از واسط خط فرمان Firebase، یا با Cloud Firestore مدیریت REST API مستقر کنید.

به‌روزرسانی‌های Cloud Firestore Security Rules ممکن است تا یک دقیقه طول بکشد تا بر پُرسمان‌ها و شنوندگان جدید تأثیر بگذارد. اما ممکن است تا ۱۰ دقیقه طول بکشد تا تغییرات کاملاً منتشر شود و بر شنوندگان فعال تأثیر بگذارد.

استفاده از کنسول Firebase

برای راه‌اندازی و استقرار اولین مجموعه قوانین خود، برای پایگاه داده پیش‌فرض در خود پروژه، به پایگاه‌های داده و ذخیره‌سازی > Firestore > بروید قوانین برگه در کنسول Firebase.

اگر چندین پایگاه داده برای پروژه‌تان ایجاد کنید، می‌توانید Cloud Firestore Security Rules را برای هر پایگاه داده مستقر کنید. در کنسول Firebase، از گزینشگر پایگاه داده برای جابه‌جایی بین پایگاه داده پیش‌فرض و هر پایگاه داده اضافی استفاده کنید.

قوانینتان را در ویرایشگر آنلاین بنویسید، سپس روی انتشار کلیک کنید.

استفاده از کنسول Google Cloud

می‌توانید Cloud Firestore Security Rules را مستقیماً در کنسول Google Cloud مدیریت و مستقر کنید. ویرایشگر قوانین برای Firestore در حالت «بومی» در هر دو نسخه Standard و Enterprise دردسترس است.

مجوزهای لازم

برای مدیریت و استقرار قوانین امنیتی در کنسول Google Cloud، به اجازه‌های IAM زیر نیاز دارید:

  • firebaserules.releases.create
  • firebaserules.releases.delete
  • firebaserules.releases.update
  • firebaserules.rulesets.create
  • firebaserules.rulesets.delete
  • firebaserules.rulesets.list
  • firebaserules.rulesets.test (برای استفاده از شبیه‌ساز قوانین لازم است)

برای استقرار قوانین در کنسول Google Cloud:

  1. در کنسول Google Cloud، به صفحه پایگاه‌های داده بروید.
  2. روی شناسه پایگاه داده‌ای که می‌خواهید مدیریت کنید کلیک کنید.
  3. در منوِ پیمایش، روی امنیت کلیک کنید.
  4. روی برگه قوانین Firestore کلیک کنید.
  5. در ویرایشگر قوانین، قوانینتان را مشاهده کنید. برای ویرایش، روی مجموعه قوانین جدید یا شبیه‌سازی مجموعه قوانین کلیک کنید، سپس قوانینتان را اصلاح کنید.
  6. روی انتشار کلیک کنید تا تغییراتتان اعمال شود.

همچنین می‌توانید مجموعه‌قوانین قبلی را در خط زمان مشاهده کنید و آن‌ها را شبیه‌سازی یا بازیابی کنید.

استفاده از واسط خط فرمان Firebase

همچنین می‌توانید بااستفاده از واسط خط فرمان Firebase، قوانین را مستقر کنید. استفاده از CLI به شما امکان می‌دهد قوانین خود را تحت کنترل نسخه با کد برنامه خود نگه دارید و قوانین را به‌عنوان بخشی از فرایند استقرار موجود خود مستقر کنید.

// Set up Firestore in your project directory, creates a .rules file
firebase init firestore

// Edit the generated .rules file to your desired security rules
// ...

// Deploy rules for all configured databases
firebase deploy --only firestore

بهبود امنیت Cloud Storage

برنامه‌هایتان از ویژگی‌های پایگاه داده قدرتمند Cloud Firestore و ویژگی‌های ذخیره‌سازی و مدیریت فایل Cloud Storage بهره‌مند خواهند شد. استفاده از این محصولات باهم، امنیت برنامه را نیز تقویت می‌کند، زیرا Cloud Firestore می‌تواند الزامات مجوز قابل‌استفاده توسط «قوانین امنیتی Firebase» را برای هر دو محصول ضبط کند. برای اطلاعات بیشتر، راهنمای Cloud Storage را ببینید.

مراحل بعدی