راهنمای مفهوم پیوند OAuth

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

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

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

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

شرایط کلیدی

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

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

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

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

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

  این جریان به دو نقطه پایانی نیاز دارد:

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

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

• نشانه دسترسی: نشانه ای که به سرویس شما اجازه دسترسی به بخش هایی از داده های کاربر را می دهد. توکن های دسترسی با هر کاربر خاص مرتبط هستند و باید غیرقابل حدس زدن باشند.

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

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

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

جریان کد مجوز را می توان به صورت زیر خلاصه کرد:

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

جریان کد ضمنی را می توان به صورت زیر خلاصه کرد:

1. Action شما از کاربر می‌پرسد که آیا می‌خواهد حساب خود را با سرویس شما پیوند دهد.
2. پس از اینکه کاربر با پیوند دادن حساب‌ها موافقت کرد، Google نقطه پایانی مجوز شما را در مرورگر کاربر باز می‌کند.
3. کاربر وارد سیستم می‌شود (اگر قبلاً وارد سیستم نشده باشد) و به Google اجازه می‌دهد با API شما به داده‌های خود دسترسی داشته باشد (اگر قبلاً مجوز نداده باشد).
4. سرویس شما یک نشانه دسترسی ایجاد می‌کند و با هدایت مرورگر کاربر به Google با علامت دسترسی پیوست شده به درخواست، آن را به Google برمی‌گرداند.
5. پس از اینکه کاربر جریان پیوند حساب را کامل کرد، Google APIهای سرویس شما را فراخوانی می کند و رمز دسترسی را با هر درخواست پیوست می کند. سرویس شما تأیید می‌کند که نشانه دسترسی به Google مجوز دسترسی به API را می‌دهد و سپس تماس API را تکمیل می‌کند.

جریان کد مجوز اساسی به شرح زیر است:

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

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

این بخش به جریان های مختلفی می پردازد که می تواند با پیوند OAuth رخ دهد.

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

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

توجه: یک خط از Webhook به کاربر نشان دهنده پاسخ ساده ای است که شما ایجاد و سفارشی می کنید. خطوط ترسیم شده از Assistant to User نشان دهنده اعلان‌هایی است که متعلق به Assistant هستند و گزینه‌های محدودی برای سفارشی‌سازی دارند (درخواست‌هایی که نیاز به مجوز دارند همیشه متعلق به Assistant هستند). از دیدگاه کاربر، هر دو نوع پاسخ از دستیار ارائه می شود.

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

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

جریان 1: کاربر با جریان ضمنی وارد سیستم می شود

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

پس از اینکه کاربر وارد سیستم شد و اعتبار آنها تأیید شد، سرویس شما یک رمز دسترسی طولانی مدت ایجاد می کند و آن را به Google برمی گرداند. در این مرحله، هویت کاربر در Action شما به حسابی که با آن وارد شده است پیوند داده می‌شود و رمز دسترسی به هر تماس API که Google با APIهای سرویس شما می‌کند، پیوست می‌شود.

جریان 2: کاربر با جریان کد مجوز وارد سیستم می شود

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

پس از اینکه کاربر وارد سیستم شد و اعتبار آنها تأیید شد، سرویس شما یک کد مجوز ایجاد می کند و آن را به Google برمی گرداند.

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