ورود به سیستم Google با APIهای FedCM

این راهنما در مورد پذیرش APIهای FedCM توسط کتابخانه پلتفرم Google Sign-in بحث می کند. موضوعات شامل جدول زمانی و مراحل بعدی برای به‌روزرسانی سازگار با گذشته کتابخانه، نحوه انجام ارزیابی تأثیر و تأیید اینکه ورود کاربر همچنان مطابق انتظار عمل می‌کند، و در صورت نیاز، دستورالعمل‌هایی برای به‌روزرسانی برنامه وب شما. گزینه های مدیریت دوره انتقال و نحوه دریافت کمک نیز پوشش داده شده است.

وضعیت کتابخانه

همه برنامه‌های وب جدید از استفاده از کتابخانه پلتفرم منسوخ Google Sign-in مسدود می‌شوند، در حالی که برنامه‌هایی که از کتابخانه استفاده می‌کنند می‌توانند تا اطلاع ثانوی ادامه دهند. تاریخ غروب نهایی (خاموش شدن) برای کتابخانه تعیین نشده است. برای اطلاعات بیشتر به لغو حمایت و غروب آفتاب مراجعه کنید.

یک به‌روزرسانی سازگار با عقب، APIهای FedCM را به کتابخانه ورود به سیستم Google اضافه می‌کند. در حالی که اکثر تغییرات یکپارچه هستند، این به‌روزرسانی تفاوت‌هایی را برای درخواست‌های کاربر ، مجوزهای iframe-policy و Content Security Policy (CSP) ایجاد می‌کند. این تغییرات ممکن است بر برنامه وب شما تأثیر بگذارد و نیاز به تغییر در کد برنامه و پیکربندی سایت داشته باشد.

در طول دوره انتقال، یک گزینه پیکربندی کنترل می‌کند که آیا APIهای FedCM در هنگام ورود به سیستم کاربر استفاده شود یا خیر.

پس از دوره انتقال، APIهای FedCM برای همه برنامه‌های وب که از کتابخانه ورود به سیستم Google استفاده می‌کنند اجباری است.

جدول زمانی

آخرین به روز رسانی سپتامبر 2024

اینها تاریخ ها و تغییراتی هستند که بر رفتار ورود به سیستم کاربر تأثیر می گذارد:

  • مارس 2023 لغو پشتیبانی از کتابخانه پلتفرم Google Sign-in.
  • ژوئیه 2024 دوره انتقال آغاز می‌شود و پشتیبانی کتابخانه پلتفرم Google Sign-in برای APIهای FedCM اضافه می‌شود. به‌طور پیش‌فرض، Google درصد درخواست‌های ورود به سیستم کاربر را با استفاده از FedCM در این مدت کنترل می‌کند. برنامه های وب ممکن است به صراحت این رفتار را با پارامتر use_fedcm لغو کنند.
  • مارس 2025 پذیرش اجباری APIهای FedCM توسط کتابخانه پلتفرم Google Sign-in، پس از آن پارامتر use_fedcm نادیده گرفته می‌شود و همه درخواست‌های ورود به سیستم کاربر از FedCM استفاده می‌کنند.

مراحل بعدی

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

  1. ارزیابی تأثیر را انجام دهید و در صورت نیاز، برنامه وب خود را به روز کنید. این رویکرد ارزیابی می‌کند که آیا ویژگی‌هایی که نیاز به تغییر در برنامه وب شما دارند، استفاده می‌شوند یا خیر. دستورالعمل ها در بخش بعدی این راهنما ارائه شده است.
  2. به کتابخانه Google Identity Services (GIS) بروید . انتقال به جدیدترین و پشتیبانی شده از کتابخانه ورود به سیستم به شدت توصیه می شود. این کار را با پیروی از این دستورالعمل ها انجام دهید.
  3. هیچ کاری نکن وقتی کتابخانه ورود به سیستم Google برای ورود به سیستم کاربر به APIهای FedCM منتقل شود، برنامه وب شما به طور خودکار به روز می شود. این کمترین کار است، اما این خطر وجود دارد که کاربران نتوانند به برنامه وب شما وارد شوند.

ارزیابی تاثیر را انجام دهید

این دستورالعمل‌ها را دنبال کنید تا مشخص کنید که آیا برنامه وب شما می‌تواند به‌طور یکپارچه از طریق یک به‌روزرسانی سازگار با عقب به‌روزرسانی شود یا برای جلوگیری از عدم امکان ورود کاربران در زمانی که کتابخانه پلتفرم Google Sign-in به طور کامل از APIهای FedCM استفاده می‌کند، تغییرات لازم است.

راه اندازی

APIهای مرورگر و آخرین نسخه کتابخانه پلتفرم Google Sign-in برای استفاده از FedCM در هنگام ورود کاربر ضروری است.

قبل از رفتن بیشتر:

  • به آخرین نسخه Chrome for Desktop به‌روزرسانی کنید. Chrome for Android به نسخه M128 یا جدیدتر نیاز دارد و نمی‌توان آن را با استفاده از نسخه‌های قبلی آزمایش کرد.
  • هنگام راه اندازی کتابخانه پلتفرم Google Sign-in در برنامه وب خود، use_fedcm روی true تنظیم کنید. به طور معمول، مقداردهی اولیه به نظر می رسد:
    • gapi.client.init({use_fedcm: true}) یا
    • gapi.auth2.init({use_fedcm: true}) یا
    • gapi.auth2.authorize({use_fedcm: true}) .
  • نسخه‌های حافظه پنهان کتابخانه پلتفرم Google Sign-in را باطل کنید. معمولاً این مرحله غیرضروری است زیرا آخرین نسخه کتابخانه مستقیماً با گنجاندن api.js ، client.js یا platform.js در یک تگ <script src> در مرورگر دانلود می شود (در درخواست ممکن است از هر یک از این نام های بسته برای استفاده استفاده شود. کتابخانه).

  • تنظیمات OAuth را برای شناسه مشتری OAuth خود تأیید کنید:

    1. صفحه اعتبارنامه را باز کنید

    2. بررسی کنید که URI وب سایت شما در منابع مجاز جاوا اسکریپت گنجانده شده است. URI فقط شامل طرح و نام میزبان کاملاً واجد شرایط است. به عنوان مثال، https://www.example.com .

    3. به صورت اختیاری، اعتبارنامه ها ممکن است با استفاده از تغییر مسیر به نقطه پایانی که میزبانی می کنید به جای پاسخ به تماس جاوا اسکریپت بازگردانده شوند. در این صورت، بررسی کنید که URIهای تغییر مسیر شما در URIهای مجاز تغییر مسیر وجود دارند. URIهای تغییر مسیر شامل طرح، نام میزبان کاملاً واجد شرایط و مسیر هستند و باید با قوانین اعتبارسنجی Redirect URI مطابقت داشته باشند. برای مثال، https://www.example.com/auth-receiver .

تست کردن

پس از دنبال کردن دستورالعمل های موجود در تنظیمات:

درخواست کتابخانه ورود به سیستم Google را پیدا کنید

با بررسی درخواست کتابخانه پلتفرم Google Sign-in بررسی کنید که آیا تغییرات در خط مشی مجوزها و خط مشی امنیت محتوا ضروری است یا خیر. برای انجام این کار، با استفاده از نام و مبدا کتابخانه، درخواست را پیدا کنید:

  • در کروم، پنل DevTools Network را باز کنید و صفحه را دوباره بارگیری کنید.
  • از مقادیر موجود در ستون‌های Domain و Name برای پیدا کردن درخواست کتابخانه استفاده کنید:
    • دامنه apis.google.com و
    • نام یا api.js ، client.js یا platform.js است. مقدار خاص Name به بسته کتابخانه درخواست شده توسط سند بستگی دارد.

به عنوان مثال، در apis.google.com در ستون Domain و platform.js در ستون Name فیلتر کنید.

iframe permissions-policy را بررسی کنید

سایت شما ممکن است از کتابخانه پلتفرم Google Sign-in در داخل یک iframe متقاطع استفاده کند. اگر چنین است، به روز رسانی نیاز است.

پس از دنبال کردن دستورالعمل‌های درخواست کتابخانه ورود به سیستم Google ، درخواست کتابخانه ورود به سیستم Google را در پنل DevTools Network انتخاب کنید و سرصفحه Sec-Fetch-Site را در بخش Request Headers در تب Headers قرار دهید. اگر مقدار هدر باشد:

  • same-site یا same-origin پس از آن سیاست های متقابل مبدا اعمال نمی شود و هیچ تغییری لازم نیست.
  • در صورت استفاده از iframe ممکن است تغییرات cross-origin ضروری باشد.

برای تأیید وجود iframe:

  • پانل Elements را در Chrome DevTools انتخاب کنید و
  • از Ctrl-F برای پیدا کردن iframe در سند استفاده کنید.

اگر یک iframe پیدا شد، سند را بررسی کنید تا تماس‌هایی با توابع gapi.auth2 یا دستورالعمل‌های script src که کتابخانه ورود به سیستم Google را در iframe بارگیری می‌کنند، بررسی کنید. اگر این مورد است:

این فرآیند را برای هر iframe در سند تکرار کنید. iframes را می توان تو در تو قرار داد، بنابراین حتماً دستور مجاز را به همه iframe های مادر اطراف اضافه کنید.

سیاست امنیتی محتوا را بررسی کنید

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

پس از دنبال کردن دستورالعمل‌های درخواست کتابخانه ورود به سیستم Google ، درخواست کتابخانه ورود به سیستم Google را در پانل DevTools Network انتخاب کنید و سرصفحه Content-Security-Policy را در بخش Response Headers در تب Headers قرار دهید.

اگر سرصفحه پیدا نشد، هیچ تغییری لازم نیست. در غیر این صورت، بررسی کنید که آیا هر یک از این دستورات CSP در هدر CSP تعریف شده است یا خیر و آنها را با استفاده از موارد زیر به روز کنید:

  • افزودن https://apis.google.com/js/ ، https://accounts.google.com/gsi/ ، و https://acounts.google.com/o/fedcm/ به هر connect-src ، default-src یا دستورات frame-src .

  • افزودن به https://apis.google.com/js/bundle-name.js به دستورالعمل script-src . بر اساس بسته کتابخانه ای که سند درخواست می کند، api.js ، client.js یا platform.js را جایگزین bundle-name.js کنید.

تغییرات درخواست کاربر را بررسی کنید

برخی از تفاوت‌ها در رفتار اعلان کاربر وجود دارد، FedCM یک گفتگوی مدال را که توسط مرورگر نمایش داده می‌شود اضافه می‌کند و الزامات فعال‌سازی کاربر را به‌روزرسانی می‌کند.

Image of FedCM modal dialog

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

فعال سازی کاربر

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

  • کاربر ابتدا با استفاده از یک نمونه مرورگر جدید به یک برنامه وب وارد می شود، یا
  • GoogleAuth.signIn نامیده می شود.

امروزه، اگر کاربر قبلاً به وب‌سایت شما وارد شده باشد، می‌توانید هنگام راه‌اندازی کتابخانه ورود به سیستم Google با استفاده از gapi.auth2.init ، اطلاعات ورود به سیستم کاربر را بدون تعامل بیشتر با کاربر به دست آورید. این دیگر امکان پذیر نیست مگر اینکه کاربر ابتدا حداقل یک بار از جریان ورود به سیستم FedCM عبور کرده باشد.

با شرکت در FedCM و تماس با GoogleAuth.signIn ، دفعه بعد که همان کاربر از وب‌سایت شما بازدید می‌کند، gapi.auth2.init می‌تواند اطلاعات ورود به سیستم کاربر را در طول اولیه‌سازی بدون تعامل کاربر به دست آورد.

موارد استفاده رایج

اسناد برنامه‌نویس برای کتابخانه ورود به سیستم Google شامل راهنماها و نمونه‌های کد برای موارد استفاده رایج است. در این بخش چگونگی تأثیر FedCM بر رفتار آنها بحث می شود.

  • ادغام Google Sign-In در برنامه وب شما

    در این دمو ، یک عنصر <div> و یک کلاس دکمه را ارائه می‌کنند، و برای کاربرانی که قبلاً وارد سیستم شده‌اند، رویداد onload صفحه اعتبار کاربری را برمی‌گرداند. تعامل کاربر برای ورود به سیستم و ایجاد یک جلسه جدید لازم است.

    مقداردهی اولیه کتابخانه توسط کلاس g-signin2 انجام می شود که gapi.load و gapi.auth2.init فراخوانی می کند.

    یک حرکت کاربر، یک عنصر <div> روی رویداد onclick ، auth2.signIn در هنگام ورود به سیستم یا auth2.signOut را در هنگام خروج فراخوانی می کند.

  • ساخت دکمه ورود به سیستم Google سفارشی

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

    مقداردهی اولیه کتابخانه از طریق یک رویداد onload برای کتابخانه platform.js انجام می شود و دکمه توسط gapi.signin2.render نمایش داده می شود.

    یک حرکت کاربر، با فشار دادن دکمه ورود به سیستم، auth2.signIn را فرا می خواند.

    در نسخه ی نمایشی دو ، یک عنصر <div> ، سبک های CSS و یک گرافیک سفارشی برای کنترل ظاهر دکمه ورود به سیستم استفاده می شود. تعامل کاربر برای ورود به سیستم و ایجاد یک جلسه جدید لازم است.

    مقداردهی اولیه کتابخانه در بارگذاری سند با استفاده از یک تابع start که gapi.load ، gapi.auth2.init و gapi.auth2.attachClickHandler را فراخوانی می کند، انجام می شود.

    یک حرکت کاربر، یک عنصر <div> onclick رویداد، auth2.signIn را با استفاده از auth2.attachClickHandler در هنگام ورود به سیستم یا auth2.signOut در هنگام خروج فراخوانی می کند.

  • نظارت بر وضعیت جلسه کاربر

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

    مقداردهی اولیه کتابخانه با فراخوانی مستقیم gapi.load ، gapi.auth2.init و gapi.auth2.attachClickHandler() پس از بارگیری platform.js با استفاده از script src انجام می شود.

    یک حرکت کاربر، یک عنصر <div> onclick رویداد، auth2.signIn را با استفاده از auth2.attachClickHandler در هنگام ورود به سیستم یا auth2.signOut در هنگام خروج فراخوانی می کند.

  • درخواست مجوزهای اضافی

    در این نسخه نمایشی ، از فشار دادن دکمه برای درخواست دامنه‌های OAuth 2.0 اضافی، دریافت نشانه دسترسی جدید استفاده می‌شود و برای کاربرانی که قبلاً وارد سیستم شده‌اند، رویداد onload صفحه اعتبار کاربر را برمی‌گرداند. تعامل کاربر برای ورود به سیستم و ایجاد یک جلسه جدید لازم است.

    مقداردهی اولیه کتابخانه توسط رویداد onload برای کتابخانه platform.js از طریق فراخوانی به gapi.signin2.render انجام می شود.

    یک حرکت کاربر، با کلیک بر روی عنصر <button> ، درخواستی را برای دامنه های OAuth 2.0 اضافی با استفاده از googleUser.grant یا auth2.signOut در هنگام خروج از سیستم آغاز می کند.

  • ادغام Google Sign-In با استفاده از شنوندگان

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

    مقداردهی اولیه کتابخانه در بارگذاری سند با استفاده از یک تابع start که gapi.load ، gapi.auth2.init و gapi.auth2.attachClickHandler را فراخوانی می کند، انجام می شود. سپس، auth2.isSignedIn.listen و auth2.currentUser.listen برای تنظیم اعلان تغییرات در وضعیت جلسه استفاده می شود. در نهایت، auth2.SignIn برای بازگرداندن اعتبار برای کاربرانی که وارد سیستم شده اند فراخوانی می شود.

    یک حرکت کاربر، یک عنصر <div> onclick رویداد، auth2.signIn را با استفاده از auth2.attachClickHandler در هنگام ورود به سیستم یا auth2.signOut در هنگام خروج فراخوانی می کند.

  • Google Sign-In برای برنامه های سمت سرور

    در این نسخه نمایشی ، از یک ژست کاربر برای درخواست کد احراز هویت OAuth 2.0 استفاده می‌شود و یک فراخوان JS یک تماس AJAX برای ارسال پاسخ به سرور باطن برای تأیید استفاده می‌کند.

    مقداردهی اولیه کتابخانه با استفاده از یک رویداد onload برای کتابخانه platform.js انجام می شود که از یک تابع start برای فراخوانی gapi.load و gapi.auth2.init استفاده می کند.

    یک حرکت کاربر، با کلیک بر روی یک عنصر <button> ، با فراخوانی auth2.grantOfflineAccess ، درخواست کد مجوز را آغاز می کند.

  • سکوی متقابل SSO

    FedCM برای هر نمونه مرورگر به رضایت نیاز دارد، حتی اگر کاربران Android قبلاً وارد سیستم شده باشند، رضایت یک‌باره ضروری است.

دوره انتقال را مدیریت کنید

در طول دوره انتقال، درصدی از ورود به سیستم کاربر ممکن است از FedCM استفاده کنند، درصد دقیق ممکن است متفاوت باشد و ممکن است در طول زمان تغییر کند. به‌طور پیش‌فرض، Google تعداد درخواست‌های ورود به سیستم را کنترل می‌کند که از FedCM استفاده می‌کنند، اما می‌توانید انتخاب کنید یا از استفاده از FedCM در طول دوره انتقال انصراف دهید. در پایان دوره انتقال، FedCM اجباری می شود و برای همه درخواست های ورود به سیستم استفاده می شود.

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

انتخاب کنید

ممکن است کنترل کنید که آیا همه یا برخی از تلاش‌ها برای ورود به سایت شما از APIهای FedCM استفاده می‌کنند یا خیر. برای انجام این کار، use_fedcm هنگام مقداردهی اولیه کتابخانه پلتفرم روی true قرار دهید. درخواست ورود کاربر در این مورد از APIهای FedCM استفاده می کند.

انصراف دهید

در طول دوره انتقال، درصدی از تلاش‌های کاربر برای ورود به سایت شما به طور پیش‌فرض از APIهای FedCM استفاده می‌کنند. اگر زمان بیشتری برای ایجاد تغییرات در برنامه شما نیاز است، ممکن است به طور موقت از استفاده از API های FedCM انصراف دهید. برای انجام این کار، use_fedcm هنگام مقداردهی اولیه کتابخانه پلتفرم روی false قرار دهید. درخواست ورود به سیستم کاربر در این مورد از APIهای FedCM استفاده نمی کند.

پس از پذیرش اجباری، هر گونه تنظیمات use_fedcm توسط کتابخانه پلتفرم Google Sign-in نادیده گرفته می‌شود.

کمک بگیرید

با استفاده از تگ google-signin در StackOverflow جستجو کنید یا سؤال بپرسید.