درخواست‌ها را فقط به کاربران اصالت‌سنجی‌شده محدود کنید

می‌توانید حالت کاربران اصالت‌سنجی‌شده را برای پروژه Firebase خود اعمال کنید. وقتی اجرا شود، همه درخواست‌های Gemini API ازطریق Firebase AI Logic باید از کاربران اصالت‌سنجی‌شده برنامه‌تان ارسال شود. به‌طور مشخص، کاربر نهایی برنامه‌تان باید پیش‌از ارسال درخواست به Firebase AI Logic از برنامه‌تان، بااستفاده از Firebase Authentication اصالت‌سنجی شود. اگر کاربر نهایی اصالت‌سنجی نشده باشد، درخواست مسدود می‌شود.

وقتی درخواستی مسدود شود، پاسخ خطای 401: unauthenticated خواهد بود.

مهم: حالت کاربران اصالت‌سنجی‌شده برای Firebase AI Logic مستلزم این است که اعتبارنامه‌های اصالت‌سنجی از Firebase Authentication باشد. اگر برنامه‌تان از راهکار اصالت‌سنجی دیگری استفاده می‌کند، اجرای این حالت درخواست‌های کاربرانتان را مسدود خواهد کرد.

ملاحظات مهم

به ملاحظات مهم زیر برای حالت کاربران اصالت‌سنجی‌شده توجه کنید.

توجه: اجباری کردن حالت کاربران اصالت‌سنجی‌شده یکی از راه‌های کمک به ایمن‌سازی Gemini API استفاده است، اما همچنان بسیار مهم است که Firebase App Check را نیز اجباری کنید.

وقتی حالت کاربران اصالت‌سنجی‌شده اعمال می‌شود

وقتی حالت کاربران اصالت‌سنجی‌شده اعمال می‌شود، به موارد زیر توجه داشته باشید:

• این تنظیم، تنظیمی در سطح پروژه برای Firebase AI Logic است.

  • این تنظیم برای همه برنامه‌های ثبت‌شده در پروژه اعمال می‌شود.
  • این خط‌مشی فقط برای پروژه‌ای اعمال می‌شود که در آن اجرا شده است.

• این تنظیم همه درخواست‌های ارسال‌شده ازطریق Firebase AI Logic را که اطلاعات اعتباری Firebase Authentication را ارسال نمی‌کنند مسدود می‌کند.

  • کاربر باید پیش‌از ارسال درخواست به Firebase AI Logic، ازطریق Firebase Authentication اصالت‌سنجی شود.
  • این تنظیم برای همه درخواست‌ها ازطریق Firebase AI Logic برای هر دو Gemini Developer API و Agent Platform Gemini API (formerly Vertex AI) اعمال می‌شود.
  • این تنظیم برای همه درخواست‌هایی که از الگوهای پیام‌واره سرور استفاده می‌کنند اعمال می‌شود.
  • این تنظیم را نمی‌توان براساس هر کاربر، هر میانای برنامه‌سازی کاربردی، یا هر الگو اعمال کرد.

• این تنظیم درخواست‌های Gemini API را در پروژه شما که ازطریق Firebase AI Logic نیستند مسدود نمی‌کند.

• اگر از ترکیبی / درون‌دستگاهی استفاده می‌کنید:

  • این تنظیم درخواست‌های ارسال‌شده به مدل میزبانی‌شده در فضای ابری را درصورتی‌که کاربر احراز هویت نشده باشد مسدود می‌کند.
  • این تنظیم درخواست‌های ارسال‌شده به مدل درون‌دستگاهی را مسدود نمی‌کند، صرف‌نظر از اینکه وضعیت اصالت‌سنجی کاربر چه باشد.

• اگر از Gemini Live API استفاده می‌کنید:

  • این تنظیم استفاده از Gemini Live API را برای برنامه‌های وب هنگام استفاده از Firebase AI Logic مسدود می‌کند — حتی برای کاربران اصالت‌سنجی‌شده. این شامل برنامه‌های وب بااستفاده از کیت توسعه نرم‌افزار Firebase JS یا برنامه‌های وب Flutter می‌شود.

• اگر از Firebase AI Logic REST API استفاده می‌کنید:

  • این تنظیم درخواست‌های استنتاج را که اطلاعات اعتباری Firebase Authentication ارسال نمی‌کنند مسدود می‌کند. این شامل درخواست‌های الگوهای پیام‌واره سرور مثل templateGenerateContent یا templateStreamGenerateContent می‌شود.
  • این تنظیم درخواست‌های صفحه کنترل (مانند درخواست‌های مدیریت الگوها و پیکربندی‌ها) را مسدود نمی‌کند زیرا این درخواست‌ها توسط IAM محافظت می‌شوند.

• این تنظیم درخواست‌های countTokens (Count Tokens API) را مسدود نمی‌کند.

قبل‌از اعمال حالت کاربران اصالت‌سنجی‌شده

پیش‌از اعمال حالت کاربران اصالت‌سنجی‌شده، به موارد زیر توجه کنید:

• اگر نسخه‌های موجودی از برنامه‌تان دارید که از Firebase Authentication استفاده نمی‌کنند:

  • این تنظیم درخواست‌های ارسال‌شده ازطریق Firebase AI Logic را از آن نسخه‌های موجود برنامه مسدود خواهد کرد.
  • مطمئن شوید که همه کلاینت‌های فعال به‌روز شده‌اند تا از Firebase Authentication قبل‌از اجرای حالت کاربران اصالت‌سنجی‌شده استفاده کنند.

• نسخه‌های قدیمی‌تر افزونه Flutter برای ارسال اعتبارنامه‌های Firebase Authentication با درخواست‌ها به نمونه‌سازی خاص نیاز دارند.

  • اگر برنامه‌تان از افزونه Flutter firebase_ai نسخه ۳.۱۱.۰ یا پایین‌تر (BoM نسخه ۴.۱۲.۰ یا پایین‌تر) استفاده می‌کند و Authentication را درطول نمونه‌سازی ارسال نمی‌کند، این تنظیم درخواست‌ها را ازطریق Firebase AI Logic مسدود می‌کند — حتی برای کاربران اصالت‌سنجی‌شده.
  • مطمئن شوید که همه کلاینت‌های فعال Flutter پیش‌از اعمال حالت کاربران اصالت‌سنجی‌شده به نسخه جدیدتر افزونه به‌روزرسانی شده باشند.

درصورت استفاده از نسخه‌های قدیمی‌تر افزونه، نمونه‌سازی خاصی برای Flutter لازم است

روی ارائه‌دهنده Gemini API کلیک کنید تا محتوا و کد مختص ارائه‌دهنده را در این صفحه ببینید. Gemini Developer API Vertex AI Gemini API

این نمونه‌سازی خاص فقط درصورتی لازم است که برنامه‌تان از افزونه Flutter firebase_ai نسخه ۳.۱۱.۰ یا پایین‌تر (BoM نسخه ۴.۱۲.۰ یا پایین‌تر) استفاده کند. اگر برنامه‌تان از نسخه جدیدتری از افزونه استفاده می‌کند، این نمونه‌سازی ویژه لازم نیست.

توجه: Firebase توصیه می‌کند از جدیدترین نسخه‌های کیت‌های توسعه نرم‌افزار، افزایه‌ها، و ابزارها استفاده کنید تا به جدیدترین ویژگی‌ها، رفع اشکال‌ها، و غیره دسترسی داشته باشید.

اگر حالت کاربران اصالت‌سنجی‌شده را اعمال کنید، در برنامه‌های Flutter که از نسخه‌های قدیمی‌تر افزونه استفاده می‌کنند، باید به‌طور صریح Authentication را درطول نمونه‌سازی ارسال کنید، مانند این:

// ...

final ai = await FirebaseAI.googleAI(
  auth: FirebaseAuth.instance, // for Flutter, pass in Authentication explicitly
);

// ...

راه‌اندازی Firebase Authentication

مهم: حالت کاربران اصالت‌سنجی‌شده برای Firebase AI Logic مستلزم این است که اعتبارنامه‌های اصالت‌سنجی از Firebase Authentication باشد. اگر برنامه‌تان از راهکار اصالت‌سنجی دیگری استفاده می‌کند، اجرای این حالت درخواست‌های کاربرانتان را مسدود خواهد کرد.

سند Firebase Authentication شرح‌ها و دستورالعمل‌های پیاده‌سازی را برای ارائه‌دهندگان اصالت‌سنجی پشتیبانی‌شده، ازجمله استفاده از گذرواژه‌ها، شماره‌های تلفن، ارائه‌دهندگان هویت فدراسیونی محبوب (مانند Google،‏ Facebook، و GitHub)، و غیره ارائه می‌دهد.

پس‌از پیاده‌سازی Firebase Authentication در برنامه‌تان، برنامه شما به‌طور خودکار اعتبارنامه Firebase Authentication را برای کاربر اصالت‌سنجی‌شده در هر درخواست به Firebase AI Logic ارسال می‌کند.

درباره برخی‌از ارائه‌دهندگان اصالت‌سنجی به موارد زیر توجه کنید:

• احراز هویت سفارشی: باید یک کد احراز هویت امضاشده را واکشی کنید تا همراه با درخواست به Firebase AI Logic ارسال شود. برای جزئیات، به اصالت‌سنجی سفارشی مراجعه کنید.

• روش‌های اصالت‌سنجی ناشناس یا ایمیل/گذرواژه: این کاربران به‌عنوان کاربران اصالت‌سنجی‌شده درنظر گرفته می‌شوند، بنابراین درخواست‌های آن‌ها برای Firebase AI Logic مسدود نمی‌شود.

  توجه داشته باشید که اگرچه روش‌های اصالت‌سنجی ناشناس و ایمیل/گذرواژه کاربران را ملزم می‌کند برای ایجاد Firebase Authentication اعتبارنامه از برنامه شما بازدید کنند، این روش‌ها اشکال قوی اصالت‌سنجی نیستند (به‌ویژه برای محافظت از منابع پولی) زیرا به‌طور پیش‌فرض به درستی‌سنجی هویت کاربر نیاز ندارند. اگر برنامه‌تان از پیاده‌سازی پیش‌فرض این روش‌های اصالت‌سنجی استفاده می‌کند، حتی اگر حالت کاربران اصالت‌سنجی‌شده را اعمال کنید، محافظت کمتری امکان‌پذیر است. مطمئن شوید که Firebase App Check را نیز اعمال کرده باشید.

مدیریت کردن تنظیم حالت کاربران اصالت‌سنجی‌شده

تنظیمات حالت کاربران اصالت‌سنجی‌شده را در کنسول Firebase مدیریت می‌کنید.

توجه: اجباری کردن حالت کاربران اصالت‌سنجی‌شده یکی از راه‌های کمک به ایمن‌سازی Gemini API استفاده است، اما همچنان بسیار مهم است که Firebase App Check را نیز اجباری کنید.

اجازه‌ها و نقش‌های IAM لازم

مدیریت کردن تنظیم حالت کاربران اصالت‌سنجی‌شده به اجازه firebasevertexai.configs.update نیاز دارد که به‌طور پیش‌فرض در این نقش‌های «مدیریت هویت و دسترسی» گنجانده شده است: «مالک»، «ویرایشگر»، «سرپرست Firebase»، و «سرپرست Firebase AI Logic».

اجرای حالت کاربران اصالت‌سنجی‌شده

نحوه اعمال حالت کاربران اصالت‌سنجی‌شده برای پروژه Firebase شما:

1. اگر قبلاً این کار را نکرده‌اید، ملاحظات مهم برای حالت کاربران اصالت‌سنجی‌شده را در بخش‌های قبلی این راهنما مرور کنید.

2. اگر قبلاً این کار را نکرده‌اید، Firebase Authentication را در برنامه‌تان راه‌اندازی کنید (همان‌طور که قبلاً در این راهنما توضیح داده شد).

3. اجرای حالت کاربران اصالت‌سنجی‌شده:

   1. در کنسول Firebase، به سرویس‌های هوش مصنوعی > منطق هوش مصنوعی > زبانه تنظیمات بروید.

   2. در بخش حالت کاربران اصالت‌سنجی‌شده، کلید کنار اجرای حالت کاربران اصالت‌سنجی‌شده را به اجراشده تغییر دهید.

   3. کادر گفتگوی تأیید را مرور کنید و سپس روی تأیید کلیک کنید.

توقف اجرای حالت کاربران اصالت‌سنجی‌شده

اگر اجرای حالت کاربران اصالت‌سنجی‌شده را متوقف کنید، به موارد زیر توجه داشته باشید:

• درخواست‌های ارسال‌شده ازطریق Firebase AI Logic که اطلاعات کاربری Firebase Authentication را ارسال نمی‌کنند مجاز خواهند بود.
• این تنظیم سراسر پروژه برای Firebase AI Logic است.

در اینجا نحوه توقف اجرای حالت کاربران اصالت‌سنجی‌شده برای پروژه Firebase شما آمده است:

1. در کنسول Firebase، به سرویس‌های هوش مصنوعی > منطق هوش مصنوعی > زبانه تنظیمات بروید.

2. در بخش حالت کاربران اصالت‌سنجی‌شده، اجرای حالت کاربران اصالت‌سنجی‌شده را خاموش کنید.

3. کادر گفتگوی تأیید را مرور کنید و سپس روی تأیید کلیک کنید.