ورود به سیستم Google مبتنی بر OAuth "کارآمد شده» راهنمای مفهوم پیوند دادن

نوع پیوند «کارآمد» ورود به سیستم Google مبتنی بر OAuth، ورود به سیستم Google را به پیوند حساب مبتنی بر OAuth اضافه می کند. اگر از این نوع پیوند در Action خود استفاده می کنید، جریان با Google Sign-In شروع می شود، که به شما امکان می دهد بررسی کنید که آیا اطلاعات نمایه Google کاربر در سیستم شما وجود دارد یا خیر. اگر اینطور نباشد، یک جریان استاندارد OAuth شروع می شود. با ارائه ترکیبی از این دو نوع پیوند، کاربران شما می توانند هویت خود را در Action شما با یک حساب Google یا غیر Google مرتبط کنند. در صورت انتخاب، می‌توانند یک حساب کاربری جدید با اطلاعات نمایه Google خود ایجاد کنند.

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

  • شما یک Action دارید که چندین پلتفرم را در بر می گیرد (به عنوان مثال، اگر Action شما با یک برنامه Android کار می کند).
  • شما یک سیستم احراز هویت موجود دارید و می‌خواهید به کاربران اجازه دهید هویت خود را با حساب‌های غیر Google مرتبط کنند. برای مثال، اگر یک برنامه وفاداری ارائه می‌دهید و می‌خواهید مطمئن شوید که کاربر امتیازهای جمع‌شده در حساب موجود خود را از دست نمی‌دهد.

برای تأیید اینکه پیوند ساده راه حل مناسبی برای شماست، به صفحه نوع پیوند حساب خود را انتخاب کنید.

اصطلاحات کلیدی

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

  • کد شناسه Google: یک ادعای امضا شده از هویت کاربر که حاوی اطلاعات اولیه نمایه Google کاربر (نام، آدرس ایمیل و عکس نمایه آنها) است. توکن Google ID یک نشانه وب JSON (JWT) است. نمونه زیر نمونه ای از رمزگشایی شده است:
{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}

  • user.verificationStatus : ویژگی تنظیم شده توسط سیستم برای نشان دادن اینکه آیا جلسه فعلی کاربر تایید شده دارد یا خیر.

  • user.accountLinkingStatus : ویژگی تنظیم شده توسط سیستم برای نشان دادن اینکه آیا کاربر در جلسه فعلی هویت پیوندی دارد یا خیر.

  • صحنه سیستم پیوند حساب: صحنه از پیش تعریف شده ای که جریان تایید را برای پیوند دادن حساب ها پیاده سازی می کند و می تواند متناسب با موارد استفاده خاص سفارشی شود.

  • جریان کد مجوز: یک جریان OAuth 2.0 که می توانید با پیوندهای ساده پیاده سازی کنید. این جریان به دو نقطه پایانی نیاز دارد:

    • نقطه پایانی مجوز: نقطه پایانی که رابط کاربری ورود به سیستم را به کاربرانی که قبلاً وارد سیستم نشده‌اند ارائه می‌کند. رضایت دسترسی درخواستی را در قالب یک کد مجوز کوتاه مدت ثبت می‌کند.
    • نقطه پایانی تبادل رمز: این نقطه پایانی مسئول دو نوع مبادله است:
      1. یک کد مجوز را برای یک نشانه رفرش طولانی مدت و یک رمز دسترسی کوتاه مدت مبادله می کند. این تبادل زمانی اتفاق می‌افتد که کاربر از جریان پیوند حساب عبور کند.
      2. یک نشانه رفرش طولانی مدت را با یک توکن دسترسی کوتاه مدت مبادله می کند. این مبادله زمانی اتفاق می‌افتد که گوگل به یک توکن دسترسی جدید نیاز دارد، زیرا رمز دسترسی منقضی شده است.

  • جریان کد ضمنی: یک جریان OAuth 2.0 که می توانید با پیوندهای ساده پیاده سازی کنید. این جریان فقط به یک نقطه پایانی مجوز نیاز دارد. در طول این جریان، Google نقطه پایانی مجوز شما را در مرورگر کاربر باز می‌کند. اگر ورود به سیستم موفقیت آمیز باشد، یک رمز دسترسی طولانی مدت به Google برمی گردانید. این نشانه دسترسی اکنون در هر درخواست ارسال شده از دستیار به Action شما گنجانده شده است.

  • نشانه دسترسی: نشانه ای که به سرویس شما اجازه دسترسی به بخش هایی از داده های کاربر را می دهد. توکن های دسترسی با هر کاربر جداگانه مرتبط هستند.

  • Refresh Token: توکنی که پس از انقضای توکن دسترسی کوتاه مدت با یک توکن دسترسی جدید مبادله می شود.

پیش نیازها

برای استفاده از نوع پیوند ساده، به موارد زیر نیاز دارید:

  • یک سرور OAuth 2.0

  • نقطه پایانی تبادل توکن

    نقطه پایانی تبادل توکن باید گسترش یابد تا پشتیبانی از پروتکل‌های Google برای پیوند خودکار و ایجاد حساب از یک نشانه شناسه اضافه شود (یعنی پارامترهای intent=get و intent=create در درخواست‌ها به این نقطه پایانی اضافه کنید).

چگونه کار می کند

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

جریان اساسی به شرح زیر است:

  1. اقدام شما از کاربر برای دسترسی به نمایه Google خود رضایت می‌خواهد.
  2. پس از رضایت کاربر، Action شما یک رمز Google ID دریافت می کند که حاوی اطلاعات نمایه Google کاربر است.
  3. برای خواندن محتوای نمایه باید رمز را تأیید و رمزگشایی کنید.
  4. Your Action از این نشانه برای بررسی اینکه آیا اطلاعات نمایه Google کاربر در سیستم شما وجود دارد یا خیر استفاده می کند.
    1. در این صورت، کاربر قبلاً با حساب Google خود وارد سیستم شما شده است و دستیار هویت کاربر را با حساب Google خود پیوند می دهد. کاربر می تواند مکالمه با دستیار را در حالی که حسابش مرتبط است ادامه دهد.
    2. اگر اینطور نیست، مرحله 5 را ببینید.
  5. کاربر می تواند الف) یک حساب کاربری جدید با اطلاعات نمایه Google خود ایجاد کند یا ب) با حساب دیگری وارد سیستم شما شود. انتخاب هایی که به کاربر ارائه می شود بر اساس فعال یا غیرفعال کردن ایجاد حساب از طریق صدا متفاوت است. اگر کاربر انتخاب کند که با حساب دیگری وارد سیستم شما شود، جریان استاندارد OAuth شروع می شود.
  6. پس از اینکه کاربر یک حساب کاربری جدید ایجاد کرد یا با ارائه دهنده دیگری وارد سیستم شد، سرویس شما یک رمز دسترسی به Google برمی گرداند. (اگر از جریان کد مجوز استفاده می‌کنید، سرویس شما یک نشانه تازه‌سازی را نیز برمی‌گرداند.)
  7. کاربر اکنون می‌تواند در حالی که حسابش مرتبط است، به مکالمه با دستیار ادامه دهد.

جریان های پیوندی ساده

این بخش به جریان‌های مختلفی می‌پردازد که می‌توانند با پیوندهای ساده رخ دهند. این نمودارها به جای جریان کد ضمنی ، جریان‌هایی را که با جریان کد مجوز رخ می‌دهند، بررسی می‌کنند و فرض می‌کنند که از Actions Builder استفاده می‌کنید.

هر جریان شامل این مراحل متداول پس از فراخوانی Action توسط کاربر است:

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

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

جریان با ایجاد حساب صوتی فعال است

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

جریان 1: اطلاعات کاربر در سیستم شما وجود دارد

در این حالت، کاربری که توسط user@gmail.com نشان داده می‌شود در باطن شما وجود دارد، بنابراین نقطه پایانی تبادل توکن شما یک توکن را برای کاربر برمی‌گرداند. هویت کاربر در Action شما اکنون به حساب Google او پیوند داده شده است. درخواست اصلی کاربر ( "Order my usual" ) با هدف کاربر order_drink. وب‌هوک شما سپس تحقق هدف منطبق را انجام می‌دهد و پایگاه داده شما را برای سفارش معمول user@gmail.com جستجو می‌کند. سپس کاربر می تواند مکالمه خود را با Assistant ادامه دهد.

جریان 2: اطلاعات کاربر وجود ندارد و کاربر حساب کاربری ایجاد می کند

از آنجایی که ایجاد حساب از طریق voice را فعال کرده‌اید و user@gmail.com در باطن شما وجود ندارد، دستیار از کاربر می‌پرسد که آیا می‌خواهد یکی از موارد زیر را انجام دهد:

الف) با استفاده از اطلاعات نمایه گوگل آنها یک حساب کاربری جدید در سیستم خود ایجاد کنید که از طریق صدا انجام می شود

ب) با حساب دیگری وارد سیستم خود شوید

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

پس از ایجاد حساب، سرویس شما یک نشانه دسترسی و نشانه رفرش را برای حساب جدید ایجاد شده برمی گرداند. هویت کاربر در Action شما اکنون به حساب Google او پیوند داده شده است. درخواست اصلی کاربر ( "Order my usual" ) با هدف کاربر order_drink. سپس وب‌هوک شما انجام هدف منطبق را انجام می‌دهد و از پایگاه داده شما برای سفارش معمول user@gmail.com سؤال می‌کند، که هنوز وجود ندارد زیرا کاربر جدید است. سپس Action شما می‌تواند از کاربر بپرسد که چه چیزی را می‌خواهد سفارش دهد.

جریان 3: اطلاعات کاربر وجود ندارد و کاربر با حساب دیگری وارد می شود

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

الف) با استفاده از اطلاعات نمایه گوگل آنها یک حساب کاربری جدید در سیستم خود ایجاد کنید که از طریق صدا انجام می شود

ب) با حساب دیگری وارد سیستم خود شوید

در این حالت، کاربر انتخاب می کند که با حساب دیگری وارد سیستم شود که جریان استاندارد OAuth را شروع می کند. اگر جریان در یک دستگاه فقط صدا شروع شود، Google اجرا را به تلفن منتقل می کند. سپس Google نقطه پایانی مجوز شما را در مرورگر کاربر باز می‌کند و بسته به پیکربندی شما، کاربر می‌تواند انتخاب کند که الف) با یک حساب موجود که از Google Sign-In استفاده نمی‌کند وارد سرویس شما شود یا ب) یک حساب جدید ایجاد کند. حساب با استفاده از ارائه دهنده دیگری. برای اطلاعات بیشتر در مورد جریان OAuth، راهنمای مفهوم پیوند OAuth را ببینید.

پس از تأیید اعتبار کاربر، سرویس شما یک نشانه دسترسی و یک نشانه تازه‌سازی را به Google برمی‌گرداند. هویت کاربر در Action شما اکنون به یک حساب غیر Google مرتبط شده است. درخواست اصلی کاربر ( "Order my usual" ) با هدف کاربر order_drink. سپس وب‌هوک شما انجام هدف منطبق را انجام می‌دهد و از پایگاه داده شما برای سفارش معمول user@gmail.com سؤال می‌کند، که هنوز وجود ندارد زیرا کاربر جدید است. سپس Action شما می‌تواند از کاربر بپرسد که چه چیزی را می‌خواهد سفارش دهد یا از او بخواهد سفارش معمول خود را تنظیم کند.

جریان با ایجاد حساب صوتی غیرفعال است

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

جریان 4: اطلاعات کاربر وجود ندارد

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

پس از تأیید اعتبار کاربر، سرویس شما یک نشانه دسترسی و یک نشانه تازه‌سازی را به Google برمی‌گرداند. هویت کاربر در Action شما اکنون به یک حساب غیر Google مرتبط شده است. درخواست اصلی کاربر ( "Order my usual" ) با هدف کاربر order_drink. سپس وب‌هوک شما انجام هدف منطبق را انجام می‌دهد و از پایگاه داده شما برای سفارش معمول user@gmail.com سؤال می‌کند، که هنوز وجود ندارد زیرا کاربر جدید است. سپس Action شما می تواند از کاربر بخواهد تا سفارش معمول خود را تنظیم کند.