راهنمای مفهومی OAuth و Google Sign-In (Dialogflow)

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

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

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

برای تأیید اینکه OAuth و Google Sign-In راه حل مناسبی برای شما هستند، به صفحه انتخاب نوع پیوند حساب خود مراجعه کنید.

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

قبل از اینکه درباره نحوه عملکرد OAuth و Google Sign-in بخوانید، با شرایط زیر آشنا شوید:

• کد شناسه 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"
}

• هدف کمکی ورود به حساب: هدف کمکی که برای درخواست جریان پیوند حساب از دستیار با آن تماس می‌گیرید. برای اطلاعات بیشتر، ورود به حساب را ببینید.
  • رشته زمینه: یک رشته سفارشی که به هدف کمکی ورود به سیستم حساب اضافه می کنید و به کاربر می گوید که چرا می خواهید حسابش را پیوند دهید.
• جریان کد مجوز: یک جریان OAuth 2.0 که می توانید با OAuth + Google Sign-In پیاده سازی کنید. این جریان به دو نقطه پایانی نیاز دارد:
  • نقطه پایانی مجوز: نقطه پایانی که رابط کاربری ورود به سیستم را به کاربرانی که قبلاً وارد سیستم نشده‌اند ارائه می‌کند. رضایت دسترسی درخواستی را در قالب یک کد مجوز کوتاه مدت ثبت می‌کند.
  • نقطه پایانی تبادل رمز: این نقطه پایانی مسئول دو نوع مبادله است:
    1. یک کد مجوز را برای یک نشانه رفرش طولانی مدت و یک رمز دسترسی کوتاه مدت مبادله می کند. این تبادل زمانی اتفاق می‌افتد که کاربر از جریان پیوند حساب عبور کند.
    2. یک نشانه رفرش طولانی مدت را با یک توکن دسترسی کوتاه مدت مبادله می کند. این مبادله زمانی اتفاق می‌افتد که گوگل به یک توکن دسترسی جدید نیاز دارد، زیرا رمز دسترسی منقضی شده است.
• جریان کد ضمنی: یک جریان OAuth 2.0 که می توانید با OAuth + Google Sign-In پیاده سازی کنید. این جریان فقط به یک نقطه پایانی مجوز نیاز دارد. در طول این جریان، Google نقطه پایانی مجوز شما را در مرورگر کاربر باز می‌کند. اگر ورود به سیستم موفقیت آمیز باشد، یک رمز دسترسی طولانی مدت به Google برمی گردانید. این نشانه دسترسی اکنون در هر درخواست ارسال شده از دستیار به Action شما گنجانده شده است.
• نشانه دسترسی: نشانه ای که به سرویس شما اجازه دسترسی به بخش هایی از داده های کاربر را می دهد. توکن های دسترسی با هر کاربر جداگانه مرتبط هستند.
• Refresh Token: توکنی که پس از انقضای توکن دسترسی کوتاه مدت با یک توکن دسترسی جدید مبادله می شود.

پیش نیازها

برای استفاده از نوع پیوند OAuth و Google Sign-In، به موارد زیر نیاز دارید:

• یک سرور OAuth 2

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

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

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

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

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

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

جریان های OAuth و GSI

این بخش به جریان های مختلفی می پردازد که می توانند با OAuth و GSI رخ دهند. این نمودارها جریان‌هایی را که با جریان کد مجوز رخ می‌دهند به جای جریان کد ضمنی ، بررسی می‌کنند و فرض می‌کنیم که از Dialogflow به عنوان راه‌حل درک زبان طبیعی برای Action خود استفاده می‌کنید.

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

در جریان بالا، actions.intent.SIGN_IN راهنما را با یک رشته زمینه که سفارشی می کنید فراخوانی می کنید. این هدف از کاربر برای دسترسی به اطلاعات نمایه Google خود اجازه می خواهد. پس از رضایت کاربر، دستیار درخواستی را ارسال می کند که حاوی اطلاعات نمایه برای user@gmail.com است.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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