مهاجرت از Google Sign-In

این راهنما به شما کمک می‌کند تا تغییرات و مراحل لازم برای انتقال موفقیت‌آمیز کتابخانه‌های جاوا اسکریپت از کتابخانه پلتفرم Google Sign-In قبلی به کتابخانه جدیدتر Google Identity Services برای احراز هویت را درک کنید.

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

احراز هویت و مجوز

احراز هویت مشخص می‌کند که شخص چه کسی است، و معمولاً به عنوان ثبت نام یا ورود به سیستم کاربر شناخته می‌شود. مجوز فرآیند اعطای یا رد دسترسی به داده ها یا منابع است. به عنوان مثال، برنامه شما رضایت کاربر شما را برای دسترسی به Google Drive کاربر درخواست می کند.

مانند کتابخانه پلتفرم Google Sign-In قبلی، کتابخانه جدید خدمات هویت Google برای پشتیبانی از فرآیندهای احراز هویت و مجوز ساخته شده است.

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

اگر مورد استفاده شما فقط مربوط به احراز هویت است، به خواندن این صفحه ادامه دهید.

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

چه چیزی تغییر کرده است

برای کاربران، کتابخانه Google Identity Services پیشرفت‌های متعددی در قابلیت استفاده ارائه می‌دهد. نکات برجسته عبارتند از:

• جدید با اصطکاک کم با یک ضربه و جریان های ورود خودکار به سیستم با گام های جداگانه کمتر،
• یک دکمه ورود به سیستم با شخصی سازی کاربر،
• نام تجاری ثابت و رفتار یکسان ورود به سیستم در سراسر وب درک و اعتماد را بهبود می بخشد،
• به سرعت به محتوا برسید؛ کاربران می توانند مستقیماً از هر نقطه از سایت شما بدون نیاز به بازدید از صفحه ورود یا حساب کاربری، ثبت نام کرده و وارد سیستم شوند.

برای توسعه دهندگان، تمرکز ما کاهش پیچیدگی، بهبود امنیت و ادغام شما در سریع ترین زمان ممکن بوده است. برخی از این بهبودها عبارتند از:

• گزینه ای برای افزودن ورود کاربر به محتوای ثابت سایت خود فقط با استفاده از HTML،
• جداسازی احراز هویت ورود به سیستم از مجوز و به اشتراک گذاری داده های کاربر، پیچیدگی یکپارچه سازی OAuth 2.0 دیگر برای ورود کاربران به سایت شما ضروری نیست.
• هر دو حالت بازشو و تغییر مسیر همچنان پشتیبانی می شوند، اما زیرساخت OAuth 2.0 Google اکنون به نقطه پایانی ورود به سرور باطن شما هدایت می شود.
• ادغام قابلیت‌های هر دو کتابخانه قبلی Google Identity و Google API JavaScript در یک کتابخانه جدید،
• برای پاسخ‌های ورود به سیستم، اکنون می‌توانید تصمیم بگیرید که آیا از Promise استفاده کنید یا نه و غیر مستقیم از طریق توابع سبک دریافت کننده برای سادگی حذف شده است.

نمونه مهاجرت ورود به سیستم

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

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

کتابخانه پلتفرم Google Sign-In قبلی: apis.google.com/js/platform.js و کتابخانه سرویس گیرنده Google APIs برای جاوا اسکریپت : gapi.client ، دیگر برای احراز هویت و مجوز کاربر لازم نیستند. آنها با یک کتابخانه جاوا اسکریپت سرویس های هویت Google جدید جایگزین شده اند: accounts.google.com/gsi/client .

سه ماژول جاوا اسکریپت قبلی: api ، client و platform مورد استفاده برای ورود به سیستم، همگی از apis.google.com بارگیری می شوند. برای کمک به شناسایی مکان‌هایی که ممکن است کتابخانه قبلی در سایت شما گنجانده شود، معمولاً:

• دکمه ورود به سیستم پیش فرض apis.google.com/js/platform.js را بارگیری می کند،
• یک دکمه گرافیکی سفارشی apis.google.com/js/api:client.js را بارگیری می کند و
• استفاده مستقیم از gapi.client apis.google.com/js/api.js را بارگیری می کند.

در بیشتر موارد، می‌توانید به استفاده از اعتبارنامه‌های شناسه کلاینت برنامه وب موجود خود ادامه دهید. به‌عنوان بخشی از انتقال، توصیه می‌کنیم که خط‌مشی‌های OAuth 2.0 ما را مرور کنید و از کنسول API Google برای تأیید استفاده کنید، و در صورت لزوم، تنظیمات مشتری زیر را به‌روزرسانی کنید:

• برنامه‌های آزمایشی و تولیدی شما از پروژه‌های جداگانه استفاده می‌کنند و شناسه‌های مشتری خاص خود را دارند،
• نوع شناسه مشتری OAuth 2.0 "برنامه وب" است و
• HTTPS برای مبداهای مجاز جاوا اسکریپت و URIهای تغییر مسیر استفاده می شود.

کد آسیب دیده را شناسایی و آزمایش کنید

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

در برنامه‌های بزرگ یا پیچیده، یافتن همه کدهایی که تحت تأثیر منسوخ شدن ماژول gapi.auth2 قرار گرفته‌اند، ممکن است دشوار باشد. برای ثبت استفاده موجود از قابلیت‌های به زودی منسوخ شده در کنسول، مقدار کوکی G_AUTH2_MIGRATION را روی informational تنظیم کنید. در صورت تمایل، یک دونقطه و به دنبال آن یک مقدار کلید اضافه کنید تا همچنین وارد فضای ذخیره‌سازی جلسه شوید. پس از ورود به سیستم و دریافت اعتبارنامه ها را بررسی کنید یا گزارش های جمع آوری شده را برای تجزیه و تحلیل بعدی به یک باطن ارسال کنید. به عنوان مثال، informational:showauth2use مبدا و URL را در یک کلید ذخیره سازی جلسه به نام showauth2use ذخیره می کند.

برای تأیید رفتار برنامه زمانی که ماژول gapi.auth2 دیگر بارگیری نمی شود، مقدار کوکی G_AUTH2_MIGRATION را روی enforced تنظیم کنید. این امکان آزمایش رفتار پس از انکار را قبل از تاریخ اجرا فراهم می کند.

مقادیر احتمالی کوکی G_AUTH2_MIGRATION :

• ماژول gapi.auth2 را بارگذاری enforced .
• informational استفاده از قابلیت های منسوخ شده در کنسول JS. همچنین هنگامی که یک نام کلید اختیاری تنظیم شده است، به ذخیره سازی جلسه وارد شوید: informational:key-name .

برای به حداقل رساندن تأثیر کاربر، توصیه می شود که ابتدا این کوکی را در حین توسعه و آزمایش، قبل از استفاده در محیط های تولید، به صورت محلی تنظیم کنید.

HTML و جاوا اسکریپت

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

راه قبلی

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

راه جدید

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

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

در این مثال فقط احراز هویت، کتابخانه جدید accounts.google.com/gsi/client ، کلاس g_id_signin و شی g_id_onload جایگزین کتابخانه apis.google.com/js/platform.js قبلی و شی g-signin2 می شوند.

کد مثال علاوه بر نمایش دکمه شخصی‌سازی‌شده جدید، پنجره جدید One Tap را نیز نمایش می‌دهد. هر جا که دکمه شخصی‌سازی شده را نمایش می‌دهید، اکیداً توصیه می‌کنیم که پنجره بازشو One Tap را نیز نمایش دهید تا اصطکاک کاربر در هنگام ثبت‌نام و ورود به سیستم به حداقل برسد.

اگرچه به دلیل افزایش اصطکاک ورود به سیستم توصیه نمی شود، دکمه شخصی سازی شده جدید را می توان به تنهایی نشان داد، بدون اینکه همزمان کادر گفتگوی One Tap نمایش داده شود. برای انجام این کار، ویژگی data-auto_prompt روی false قرار دهید.

APIهای HTML و جاوا اسکریپت

مثال قبلی نشان می دهد که چگونه از API جدید HTML برای افزودن ورود به وب سایت خود استفاده کنید. از طرف دیگر، می‌توانید از API جاوا اسکریپت معادل عملکردی استفاده کنید، یا APIهای HTML و جاوا اسکریپت را در سراسر سایت خود ترکیب و مطابقت دهید.

برای مشاهده تعاملی گزینه‌های سفارشی‌سازی دکمه‌ها مانند، نوع پاسخ به تماس و ویژگی‌هایی مانند: رنگ، اندازه، شکل، متن و موضوع، کد مولد ما را بررسی کنید. می توان از آن برای مقایسه سریع گزینه های مختلف و تولید قطعه های HTML برای استفاده در سایت خود استفاده کرد.

از هر صفحه ای با یک ضربه وارد شوید

One Tap یک روش جدید با اصطکاک کم برای کاربران برای ثبت نام یا ورود به سایت شما است. این به شما امکان می دهد مستقیماً از هر صفحه ای در سایت خود ورود کاربر را فعال کنید و نیازی به بازدید کاربران از یک صفحه ورود اختصاصی را برطرف می کند. به عبارت دیگر، این امر با دادن انعطاف پذیری کاربران برای ثبت نام و ورود از صفحاتی غیر از صفحه ورود شما، اصطکاک ثبت نام و ورود را کاهش می دهد.

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

همچنین توصیه می‌کنیم g_id_signin که دکمه ورود به سیستم شخصی‌شده را نمایش می‌دهد، فقط در صفحات مدیریت حساب کاربری یا ورود به سیستم خود اضافه کنید. با نمایش دکمه در کنار سایر دکمه‌های ارائه‌دهنده هویت فدرال و فیلدهای ورود نام کاربری و رمز عبور، به کاربران حق انتخاب برای ثبت‌نام یا ورود به سیستم بدهید.

پاسخ رمزی

ورود کاربر به سیستم دیگر نیازی به درک یا کار با کدهای مجوز OAuth 2.0، دسترسی به نشانه‌ها یا بازخوانی نشانه‌ها ندارد. درعوض، از رمز شناسه JSON Web Token (JWT) برای اشتراک‌گذاری وضعیت ورود به سیستم و نمایه کاربر استفاده می‌شود. به عنوان ساده‌تر، دیگر نیازی به استفاده از روش‌های دسترسی به سبک «دریافت کننده» برای کار با داده‌های نمایه کاربر ندارید.

یک اعتبار رمز JWT ID ایمن امضا شده توسط Google بازگردانده می شود:

• به کنترل کننده پاسخ به تماس جاوا اسکریپت مبتنی بر مرورگر کاربر در حالت پاپ آپ، یا
• هنگامی که دکمه Sign In With Google ux_mode روی redirect تنظیم شده است، از طریق یک تغییر مسیر Google به نقطه پایانی ورود به سیستم شما به سرور باطن شما.

در هر دو مورد، کنترل‌کننده‌های پاسخ به تماس موجود خود را با حذف موارد زیر به‌روزرسانی کنید:

• تماس با googleUser.getBasicProfile() ،
• ارجاع به BasicProfile و فراخوانی های مرتبط به متدهای getId() ، getName() ، getGivenName() ، getFamilyName() ، getImageUrl() ، getEmail() و
• استفاده از شی AuthResponse

در عوض، از ارجاع مستقیم به زیر فیلدهای credential در شیء جدید JWT CredentialResponse برای کار با داده های نمایه کاربر استفاده کنید.

علاوه بر این، و فقط برای حالت تغییر مسیر، مطمئن شوید که از جعل درخواست بین سایتی (CSRF) جلوگیری کنید و رمز Google ID را در سرور باطن خود تأیید کنید .

برای درک بهتر نحوه تعامل کاربران با سایت شما، از قسمت select_by در CredentialResponse می توان برای تعیین نتیجه رضایت کاربر و جریان ورود خاص استفاده شده استفاده کرد.

رضایت کاربر و لغو مجوز

هنگامی که کاربر برای اولین بار وارد وب سایت شما می شود، Google از کاربر می خواهد که برای به اشتراک گذاشتن نمایه حساب خود با برنامه شما رضایت دهد. تنها پس از ارائه رضایت، نمایه کاربر با برنامه شما در یک محموله اعتبار شناسه رمز به اشتراک گذاشته می شود. لغو دسترسی به این نمایه معادل لغو یک نشانه دسترسی در کتابخانه ورود به سیستم قبلی است.

کاربران ممکن است با مراجعه به https://myaccount.google.com/permissions مجوزها را لغو کنند و برنامه شما را از حساب Google خود جدا کنند. از طرف دیگر، آنها ممکن است مستقیماً با برنامه شما با راه اندازی یک تماس API که شما پیاده سازی می کنید، ارتباط خود را قطع کنند. روش disconnect قبلی با روش revoke جدید جایگزین شده است.

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

قبلاً، auth2.signOut() می توانست برای کمک به مدیریت خروج کاربر از برنامه شما استفاده شود. هر گونه استفاده از auth2.signOut() باید حذف شود و برنامه شما باید مستقیماً وضعیت جلسه کاربر و وضعیت ورود به سیستم را مدیریت کند.

وضعیت جلسه و شنوندگان

کتابخانه جدید وضعیت ورود به سیستم یا وضعیت جلسه را برای برنامه وب شما حفظ نمی کند.

وضعیت ورود به سیستم حساب Google و وضعیت جلسه برنامه شما و وضعیت ورود به سیستم مفاهیم مجزا و مجزا هستند.

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

وقتی ورود به سیستم با Google، با یک ضربه یا ورود خودکار به سایت شما اضافه می‌شود، کاربران ابتدا باید به حساب Google خود وارد شوند تا:

• هنگام اولین ثبت نام یا ورود به سایت خود، رضایت خود را برای به اشتراک گذاشتن نمایه کاربری خود ارائه دهید،
• و بعداً برای ورود مجدد به سایت شما.

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

اکنون شما مسئول مدیریت مستقیم وضعیت ورود به سیستم برای کاربران برنامه وب خود هستید. قبلاً Google Sign-In به نظارت بر وضعیت جلسه کاربر کمک می کرد.

هر گونه ارجاعی به auth2.attachClickHandler() و کنترل کننده های بازگشت تماس ثبت شده آن را حذف کنید.

قبلاً از Listeners برای اشتراک‌گذاری تغییرات در وضعیت ورود به سیستم برای حساب Google کاربر استفاده می‌شد. شنوندگان دیگر پشتیبانی نمی شوند.

هر گونه ارجاعی به listen() ، auth2.currentUser و auth2.isSignedIn را حذف کنید.

کوکی ها

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

کوکی G_ENABLED_IDPS که توسط کتابخانه پلتفرم ورود به سیستم Google قبلی تنظیم شده است، دیگر استفاده نمی شود.

کتابخانه خدمات هویت Google جدید ممکن است به صورت اختیاری این کوکی‌های بین دامنه‌ای را بر اساس گزینه‌های پیکربندی شما تنظیم کند:

• g_state وضعیت خروج کاربر را ذخیره می کند و هنگام استفاده از پنجره بازشو با یک ضربه یا ورود خودکار تنظیم می شود،

• g_csrf_token یک کوکی دوبار ارسال است که برای جلوگیری از حملات CSRF استفاده می‌شود و زمانی تنظیم می‌شود که نقطه پایانی ورود شما فراخوانی شود. مقدار URI ورود به سیستم شما می تواند به طور صریح تنظیم شود یا ممکن است به طور پیش فرض URI صفحه فعلی باشد. هنگام استفاده از موارد زیر ممکن است نقطه پایانی ورود شما تحت این شرایط فراخوانی شود:

  • HTML API با data-ux_mode=redirect یا زمانی که data-login_uri تنظیم شده است، یا

  • JavaScript API با ux_mode=redirect و جایی که google.accounts.id.prompt() برای نمایش One Tap یا Automatic Sign in استفاده نمی شود.

اگر سرویسی دارید که کوکی‌ها را مدیریت می‌کند، حتماً دو کوکی جدید را اضافه کنید و پس از تکمیل انتقال، کوکی قبلی را حذف کنید.

اگر چندین دامنه یا زیر دامنه را مدیریت می‌کنید، برای دستورالعمل‌های بیشتر در مورد کار با کوکی g_state ، به نمایش یک ضربه در زیر دامنه‌ها مراجعه کنید.

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