راهنمای پیاده‌سازی OAuth 2.1

این راهنما نحوه صدور مجوز ایمن برای پلاتفرم «برنامه‌های متصل‌شده» را برای دسترسی به سرویس‌هایتان شرح می‌دهد. برای ادغام‌های MCP برنامه‌های متصل‌شده، اکیداً توصیه می‌کنیم از OAuth 2.1، استاندارد صنعتی برای مجوز تفویض‌شده، با کلید اثبات برای تبادل کد (PKCE) استفاده کنید تا بالاترین امنیت برای داده‌های کاربر و قابلیت اطمینان در جریان‌های «عامل‌محور» تضمین شود. پلاتفرم «برنامه‌های متصل‌شده» از نوع اعطای کد مجوز با پارامترهای «کلید اثبات برای تبادل کد» (PKCE) پشتیبانی می‌کند.

PKCE برای همه OAuth 2.1 الزامی و برای OAuth2.0 اختیاری است.

برای فعال کردن اکتشاف خودکار و ساده‌سازی فرایند آماده‌سازی، سرور مجوز شما باید از افزونه فراداده سرور مجوز که به آن «اکتشاف OAuth» نیز گفته می‌شود پشتیبانی کند.

نکته: برای جلوگیری از تجربه کاربری ناامیدکننده و نیاز به پیوند مجدد حساب‌ها، مهم‌ترین جزئیات مدیریت طول عمر «ژتون بازآوری» بااستفاده از پیونددهی پایدار است.

نحوه واکشی JSON پیکربندی توسط Gemini MCP

کنسول Gemini MCP تلاش می‌کند JSON پیکربندی شما را از نشانی‌های وب زیر، به ترتیبی که در این بخش نشان داده شده است، واکشی کند.

احتیاط: کنسول Gemini MCP از اولین نشانی وبی که پاسخی برمی‌گرداند (ازجمله خطا) استفاده می‌کند. مطمئن شوید نقطه پایانی ترجیحی‌تان دردسترس باشد و HTTP 200 را برگرداند.

اگر نشانی وب سرور مجوز شما در سطح بالای دامنه‌تان قرار دارد (برای مثال، https://auth.example.com)، Gemini دایرکتوری‌های استاندارد «شناخته‌شده» را به دامنه‌تان اضافه می‌کند و سرور را به‌ترتیب زیر جستجو می‌کند:

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

اگر نشانی وب سرور مجوزدهی شما در زیرفهرست راهنما یا مسیر خاصی در دامنه‌تان قرار دارد، برای مثال https://auth.example.com/realms/master، Gemini همان مسیرهای «well-known» را مستقیماً به آن زیرفهرست راهنما، به‌ترتیب زیر، اضافه می‌کند.

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. ‫.../realms/master/.well-known/openid-configuration (پشتیبانی از مسیر تودرتو)

قابلیت‌های JSON موردنیاز

پاسخ فراداده شما باید شامل فیلدهای زیر باشد. اگر فیلدهای اجباری وجود نداشته باشند یا انواع معتبر پیدا نشوند، ادغام ناموفق خواهد بود.

authorization_endpoint

باید نشانی وب رشته‌ای معتبر باشد.

token_endpoint

باید نشانی وب رشته‌ای معتبر باشد.

response_types_supported

باید شامل رشته code باشد.

registration_endpoint

درحال‌حاضر، «کنسول Play» به «کارخواه پویا» متکی است.

ثبت (RFC 7591). باید نقطه پایانی ثبت را در فراداده‌تان ارائه دهید یا شناسه/رمز کارخواه را مستقیماً در واسط کاربر «کنسول Play» وارد کنید.

اگر سرور مجوز شما از Dynamic Client Registration (DCR) پشتیبانی نمی‌کند، باید فیلدهای شناسه کارخواه و رمز کارخواه را به‌صورت دستی در واسط کاربر «کنسول Play» پیاده‌سازی و تکمیل کنید تا ادغام تکمیل شود.

اگر پیاده‌سازی شما از «کلید اثبات برای تبادل کد» (PKCE) یا جلسه‌های پایدار پشتیبانی می‌کند، باید فیلدهای قابلیت مربوطه (مانند روش‌های چالش و انواع اعطای مجوز) را در JSON اکتشافی خود بگنجانید. این کار به اطمینان از سازگاری با استانداردهای امنیتی و اتصال Gemini کمک می‌کند. اگر از گستره پشتیبانی می‌کنید، باید فیلد scopes_supported را اضافه کنید.

پیکربندی نمونه

پاسخ JSON معتبر زیر الزامات مشتری ما را برآورده می‌کند.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

برای مواردی که PKCE را اضافه می‌کنید، تکه‌کد زیر نمونه‌ای از آنچه را که می‌تواند در بلوک JSON گنجانده شود نشان می‌دهد.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

برای مواردی که فیلد scopes_supported را اضافه می‌کنید، قطعه زیر نمونه‌ای از آنچه را که می‌تواند در بلوک JSON گنجانده شود نشان می‌دهد.

"scopes_supported": ["mcp", "cart.order"],

جریان کد مجوز (نسخه ساده‌شده)

مراحل زیر جریان کد مجوز استاندارد را نشان می‌دهد. این توالی نشان می‌دهد که پلاتفرم «برنامه‌های متصل‌شده» دقیقاً چگونه کد دسترسی لازم را به‌طور ایمن از سرور شما دریافت می‌کند تا ازطرف کاربر اقدام کند.

1. درخواست مجوز: سطح Google تشخیص می‌دهد که باید تابع شما را فراخوانی کند، اما کاربر هنوز مجوز ندارد. روبات گپ با هدایت کردن مرورگر کاربر (یا نمایش پیوند) به نقطه پایانی مجوز شما، جریان را آغاز می‌کند.

   این درخواست شامل شناسه مشتری شما (یا شناسه مشتری تولیدشده به‌طور خودکار با DCR)، شناسه URI هدایت Gemini، و پارامترهای مهم کلید اثبات برای تبادل کد (code_challenge و code_challenge_method) است.

   نشانی‌های وب زیر را برای راه‌اندازی OAuth در فهرست مجاز قرار دهید:

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. رضایت کاربر: سرور اصالت‌سنجی شما درخواست را اعتبارسنجی می‌کند، اصالت کاربر را می‌سنجد (ورود به سیستم)، و از کاربر می‌خواهد به سطح Google اجازه دهد به داده‌ها یا سرویس او دسترسی داشته باشد.

3. اعطای کد: پس‌از اینکه کاربر موافقت کرد، سرور شما مرورگر کاربر را به RedirectURI Gemini هدایت می‌کند و کد مجوز موقتی را به نشانی وب اضافه می‌کند.

4. تبادل کد: پسای پشت Gemini درخواست POST را به نقطه پایانی کد شما ارسال می‌کند و کد مجوز را با کد دسترسی مبادله می‌کند.

   توجه: این درخواست باید شامل پارامتر PKCE (code_verifier) باشد تا ثابت شود که همان کارخواه است که جریان را شروع کرده است.

5. دسترسی اعطا شد: نقطه پایانی کد شما، کد و پارامترهای PKCE را درستی‌سنجی می‌کند، کد دسترسی و به‌صورت اختیاری ژتون بازآوری صادر می‌کند، و آن‌ها را به Gemini برمی‌گرداند.

   نکته: اگرچه ژتون‌های بازآوری اختیاری هستند، اکیداً توصیه می‌کنیم سرور صدور مجوزتان را برای صدور آن‌ها پیکربندی کنید. ژتون‌های بازآوری به پلاتفرم برنامه‌های متصل‌شده اجازه می‌دهد دسترسی را بدون نیاز به اصالت‌سنجی مجدد کاربر حفظ کند.

الزامات کلیدی «کلید اثبات برای تبادل کد»

PKCE لایه‌ای امنیتی اضافه می‌کند تا از رهگیری غیرمجاز کدهای مجوز جلوگیری کند.

احتیاط: برآورده کردن این الزامات PKCE برای مدیریت صحیح ژتون‌های دسترسی و بازآوری ضروری است، که به محافظت از داده‌های کاربر و حفظ یکپارچگی بوم‌سازگان کمک می‌کند.

• code_verifier: رشته تصادفی رمزنگاری‌شده‌ای که Gemini در ابتدای جریان تولید کرده است. این اطلاعات خصوصی نگه داشته می‌شود.
• code_challenge: تبدیل code_verifier، معمولاً درهم‌سازی SHA256. این درخواست به‌صورت عمومی ارسال می‌شود، همان‌طور که در مرحله ۱ جریان کد مجوز شرح داده شده است.
• اعتبارسنجی: نقطه پایانی کد شما (که در مرحله ۴ جریان کد مجوز شرح داده شده است) باید اعتبارسنجی کند که code_verifier دریافتی، پس‌از تبدیل، با code_challenge اصلی مطابقت داشته باشد.

اشکال‌زدایی

اطلاعات دقیق خطای پیونددهی در «کاوشگر گزارش‌ها» دردسترس است، برای فعال کردن و مشاهده خطاها، دستورالعمل‌های پایش خطاهای پیونددهی حساب در پروژه «کنسول Google» را دنبال کنید.

الزامات پیکربندی پیونددهی حساب Google

برای اطلاعات درباره پیکربندی پیونددهی حساب Google، راهنمای میانای برنامه‌سازی کاربردی زیر را بخوانید.

• پیوند دادن حساب Google با OAuth
• Your Account Linking API
• Google Account Linking API

برای ثبت موفقیت‌آمیز ادغام OAuth، باید جزئیات خاصی را درباره سرور مجوز خود پیکربندی کنید. مطمئن شوید که نقاط پایانی، اطلاعات کاربری، و دارایی‌های زیر را آماده کرده‌اید.

فیلد پیکربندی	شرح	مسئولیت توسعه‌دهنده
شناسه کارخواه و رمز	اعتبارنامه یکتایی که سرور مجوزدهی شما به‌طور خاص برای پلاتفرم «برنامه‌های متصل‌شده» تولید می‌کند. «رمز کارخواه» اعتبارنامه امن (گذرواژه) منسوب به «شناسه کارخواه» است. توجه: اگر توسعه‌دهنده «شناسه کارخواه» را صادر کرده باشد، باید آن را ارائه دهد. اگر Google شناسه کارخواه را صادر کرده باشد، ممکن است توسعه‌دهنده نیاز به ثبت یا تأیید رمز داشته باشد.	از شناسه ارائه‌شده توسط پلاتفرم در همه درخواست‌های مجوز استفاده کنید.
نقطه پایان مجوز	نشانی وبی که کاربران برای اصالت‌سنجی و اعطای رضایت به آن هدایت می‌شوند	میزبانی نقطه پایانی—برای مثال، https://yourdomain.com/oauth/authorize
نقطه پایان کد	نقطه پایان پس‌بست برای تبادل کدهای مجوز با کدهای «دسترسی/بازآوری»، و برای بازآوری کدهای منقضی‌شده.	این نقطه پایانی را میزبانی کنید—برای مثال، https://yourdomain.com/oauth/token
نقطه پایان فسخ اختیاری	نشانی وبی که وقتی کاربر قطع می‌شود، به سیستم شما اطلاع می‌دهد که یک کد را باطل کند. وقتی کاربری از داخل پلاتفرم «برنامه‌های متصل‌شده» پیوند ادغام شما را لغو کند یا آن را قطع کند، ما یک درخواست POST به نقطه پایانی /revoke حاوی ژتون «دسترسی» یا «بازآوری» ارسال خواهیم کرد. برای اطلاعات بیشتر، لغو پیوند حساب‌ها را ببینید.	میزبانی نقطه پایانی—برای مثال، https://yourdomain.com/oauth/revoke سرور شما باید این درخواست را با باطل کردن دائمی کد ارائه‌شده مدیریت کند. این کار تضمین می‌کند که هرگونه تلاش بعدی پلاتفرم «برنامه‌های متصل‌شده» برای استفاده از آن نمانک ناموفق خواهد بود و امنیت داده‌های کاربر پس‌از قطع اتصال حفظ می‌شود.
شناسه URI هدایت	نشانی وب فراخوان خاص ارائه‌شده توسط پلاتفرم که «سرور مجوز» پس‌از رضایت، کد را به آن برمی‌گرداند.	«سرور صدور مجوز» خود را پیکربندی کنید تا فقط «شناسه منبع یکسان» رسمی و ثبت‌شده را از پلاتفرم بپذیرد.
بازآوری کردن	/token با grant_type=refresh_token سازوکاری که به پلاتفرم «برنامه‌های متصل‌شده» اجازه می‌دهد تا وقتی «کد دسترسی» فعلی منقضی می‌شود، «کد دسترسی» جدیدی دریافت کند و ادغام را به‌طور یکپارچه متصل نگه دارد، بدون اینکه کاربر مجبور باشد مکرراً به سیستم وارد شود. وقتی «کد دسترسی» موجود منقضی می‌شود، پلاتفرم «برنامه‌های متصل» به‌طور خودکار درخواست POST به نقطه پایانی /token شما ارسال می‌کند. بار داده درخواست شامل grant_type=refresh_token به‌همراه «ژتون بازآوری» خواهد بود که سرورتان قبلاً صادر کرده است.	سرور شما باید «ژتون بازآوری» ارائه‌شده را اعتبارسنجی کند و «ژتون دسترسی» جدیدی در پاسخ JSON برگرداند. علاوه‌براین، برای پیاده‌سازی پیوند پایدار، باید از چرخاندن «ژتون بازآوری» درطول این تبادل اجتناب کنید. به‌جای صدور «ژتون بازآوری» جدید، دقیقاً همان «ژتون بازآوری» را در پاسخ JSON برگردانید و تاریخ انقضای آن را در پس‌بک خود تمدید کنید.
نوع پاسخ	این مورد باید روی CODE پیکربندی شود تا از جریان «کد مجوز» پشتیبانی کند.
دامنه‌ها	مجموعه اجازه‌ها و سطوح دسترسی خاصی که مشخص می‌کند این کد مجاز به انجام چه کارهایی است. این موارد باید ازقبل در پیکربندی شما تعریف شده باشد تا Google بتواند آن‌ها را درطول دست‌دهی اولیه برای صدور مجوز درخواست کند.	باید فهرستی از دامنه‌های پیش‌فرض (برای مثال، openid, profile, email) را که پلاتفرم «برنامه‌های متصل‌شده» باید هنگام شروع جریان درخواست کند ارائه دهید. دامنه‌های درخواستی باید تا حد امکان کاهش یابند (اصل حداقل امتیاز) اما برای «مسیرهای قطعی کاربر» (CUJ) که ادغام MCP شما پشتیبانی می‌کند کاملاً کافی باشند.
دارایی‌های میانای کاربر: نشان‌واره	نشان‌واره توسعه‌دهنده برای نمایش در صفحه‌های پیونددهی حساب و رضایت.	باید تصویر برداری مربعی (SVG) با ظاهر دایره‌ای و حداقل ۵۰۰ × ۵۰۰ پیکسل باشد. برای مثال، https://[partner-domain]/assets/logo.svg یا فایل SVG خام را ببینید.
پیوند دادن برنامه به زبان اصلی دستگاه (هم‌پیوندی برنامه)	برای پشتیبانی از پیوند دادن حساب مستقیماً از برنامه‌های Android یا iOS بومی، به‌شدت توصیه می‌شود که به نماهای وب استاندارد اتکا نکنید. درعوض، برای تجربه کاربری یکپارچه، اکیداً توصیه می‌شود «هم‌پیوندی برنامه» را پیاده‌سازی کنید. برای اطلاعات بیشتر، پیونددهی «حساب Google» با «هم‌پیوندی برنامه» مبتنی بر OAuth را ببینید.	درستی‌سنجی «فروشگاه Play» و App Store را تکمیل کنید و «URIهای هدایت مجدد» Google را مستقیماً در برنامه‌های بومی‌تان جاسازی کنید تا از جابه‌جایی امن و برنامه به برنامه برای صدور مجوز اطمینان حاصل کنید.
طول عمر کد	(اختیاری) مدت زمانی که «کد دسترسی» قبل‌از نیاز به بازآوری معتبر است. برای پیکربندی خط‌مشی‌های زمان‌اتمام در GAL مفید است.	زمان‌های انقضای رایج بسته به نیازهای امنیتی از چند دقیقه، ساعت، تا چند روز متغیر است—برای مثال، 30 days)

خطاهای رایج ادغام

در اینجا فهرستی از خطاهای رایج و راه‌حل‌های احتمالی مربوط به فرایند ادغام آورده شده است.

• اعطای «کد» وجود ندارد: سیستم خودکار پلاتفرم Gemini به‌طور صریح response_types_supported را برای مقدار «کد» بررسی می‌کند.
• نقطه پایانی ثبت وجود ندارد: حتی اگر سرور شما از «مستندات فراداده شناسه کارخواه» پشتیبانی کند، برنامه Gemini (که به‌عنوان کارخواه OAuth به سرور شما متصل می‌شود) درحال‌حاضر به یک registration_endpoint اختصاصی نیاز دارد تا در JSON اکتشاف وجود داشته باشد.
• خطای غیر ۲۰۰: اگر سازوکار خودکارسازی‌شده کشف فراداده Gemini به نشانی وب شناخته‌شده شما برسد و خطای ۴۰۴ یا ۵۰۰ دریافت کند، برای حدس زدن نشانی‌های وب دیگر تلاش نخواهد کرد. لطفاً مطمئن شوید نشانی وب کشف به‌طور عمومی دردسترس باشد.