دليل مفاهيم OAuth و"تسجيل الدخول بحساب Google" (Dialogflow)

يضيف نوع ربط OAuth و"تسجيل الدخول بحساب Google" تسجيل الدخول بحساب Google إلى جانب ربط الحساب المستند إلى OAuth. إذا كنت تستخدم نوع الربط هذا في الإجراء الخاص بك، سيبدأ التدفق بتسجيل الدخول بحساب Google، الذي يتيح لك التحقق من وجود معلومات الملف الشخصي للمستخدم على Google في نظامك. وإذا لم يحدث ذلك، يبدأ تدفق OAuth العادي. من خلال توفير مزيج من هذين النوعين من الروابط، يمكن للمستخدمين ربط هويتهم في الإجراء الخاص بك بحساب Google أو حساب غير تابع لشركة Google. ويمكنهم أيضًا إنشاء حساب جديد باستخدام معلومات ملفهم الشخصي على Google، إذا أرادوا.

إنّ OAuth و"تسجيل الدخول بحساب Google" هو الحل المقترَح لربط الحساب في حال انطباق أي مما يلي:

  • لديك إجراء يمتد على عدة منصات (على سبيل المثال، إذا كان الإجراء يتوافق مع تطبيق Android).
  • لديك نظام مصادقة حالي وتريد السماح للمستخدمين بربط هوياتهم بحسابات غير تابعة لشركة Google. على سبيل المثال، إذا كنت تقدّم برنامج ولاء وتريد التأكّد من أنّ المستخدم لن يفقد النقاط المتراكمة في حسابه الحالي

للتأكّد من أنّ بروتوكول OAuth و"تسجيل الدخول بحساب Google" هو الحل المناسب لك، يُرجى الاطّلاع على صفحة اختيار نوع ربط الحساب.

المصطلحات الرئيسية

قبل الاطّلاع على آلية عمل OAuth وتسجيل الدخول بحساب Google، اطّلِع على البنود التالية:

  • الرمز المميز لمعرّف Google: تأكيد موقّع لهوية المستخدم يحتوي على معلومات الملف الشخصي الأساسية للمستخدم في Google (الاسم وعنوان البريد الإلكتروني وصورة الملف الشخصي). الرمز المميز لـ Google ID هو JSON Web Token (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"
}
  • هدف المساعد في تسجيل الدخول إلى الحساب: هو هدف المساعد الذي تطلبه لطلب عملية ربط للحساب من "مساعد Google". لمزيد من المعلومات، اطّلع على تسجيل الدخول إلى الحساب.
    • سلسلة السياق: سلسلة مخصّصة تضيفها إلى الغرض من مساعد تسجيل الدخول إلى الحساب لإعلام المستخدم بسبب رغبتك في ربط حسابه.
  • مسار رمز التفويض: مسار OAuth 2.0 يمكنك تنفيذه باستخدام OAuth + تسجيل الدخول بحساب Google. يتطلّب هذا المسار نقطتَي نهاية:
    • نقطة نهاية التفويض: نقطة النهاية التي تعرض واجهة مستخدم تسجيل الدخول للمستخدمين الذين لم يسبق لهم تسجيل الدخول. وهو يسجّل الموافقة على الوصول المطلوب في شكل رمز تفويض قصير الأجل.
    • نقطة نهاية تبادل الرموز المميّزة: تكون نقطة النهاية هذه مسؤولة عن نوعَين من عمليات التبادل:
      1. تتبادل رمز التفويض مع رمز مميّز طويل الأمد لإعادة التحميل ورمز دخول قصير الأجل. يحدث هذا التبادل عندما يمر المستخدم بعملية ربط الحساب.
      2. تتبادل الرمز المميّز لإعادة التحميل طويل الأمد مع رمز دخول قصير الأجل. يحدث التبادل هذا عندما تحتاج Google إلى رمز دخول جديد بسبب انتهاء صلاحيته.
  • تدفق الرمز الضمني: هو مسار OAuth 2.0 الذي يمكنك تنفيذه باستخدام OAuth + تسجيل الدخول بحساب Google. لا يتطلب هذا المسار سوى نقطة نهاية للتفويض. وخلال هذا المسار، تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. إذا تم تسجيل الدخول بنجاح، يتم إرجاع رمز دخول طويل الأمد إلى Google. أصبح رمز الدخول هذا مضمَّنًا الآن في كل طلب يتم إرساله من "مساعد Google" إلى الإجراء الخاص بك.
  • رمز الدخول: رمز مميز يصرّح لخدمتك بالوصول إلى أجزاء من بيانات المستخدم. ترتبط رموز الدخول بكل مستخدم فردي.
  • رمز إعادة التحميل المميّز: رمز مميّز يتم استبداله برمز دخول جديد بعد انتهاء صلاحية رمز دخول قصير الأجل.

المتطلبات الأساسية

لاستخدام نوع الربط بين OAuth و"تسجيل الدخول بحساب Google"، تحتاج إلى ما يلي:

  • خادم OAuth 2

  • نقطة نهاية تبادل الرموز المميّزة

    يجب توسيع نقطة نهاية تبادل الرموز المميّزة لإتاحة استخدام بروتوكولات Google للربط التلقائي وإنشاء الحساب من رمز مميّز لرقم التعريف (أي إضافة المَعلمتَين intent=get وintent=create في الطلبات إلى نقطة النهاية هذه).

آلية العمل

يوضِّح هذا القسم الخطوات العامة التي يجب اتّباعها عند استخدام OAuth وتسجيل الدخول بحساب Google. يوضّح القسم التالي، تدفقات OAuth وGSI، التدفقات المختلفة التي يمكن أن تحدث بناءً على أ) ما إذا تم تفعيل أو إيقاف إنشاء الحساب عبر الصوت وب) ما إذا كنت تستخدم تدفق التعليمات البرمجية الضمني أو رمز التفويض.

وفي ما يلي الخطوات الأساسية:

  1. يطلب الإجراء الخاص بك من المستخدم الموافقة للوصول إلى ملفه الشخصي في Google.
  2. بعد أن يمنح المستخدم موافقته، يتلقّى الإجراء الخاص بك رمزًا مميزًا من Google ID يحتوي على معلومات الملف الشخصي الخاص بالمستخدم على Google.
  3. يجب التحقّق من الرمز المميّز وفك ترميزه لقراءة محتوى الملف الشخصي.
  4. يستخدم الإجراء الخاص بك هذا الرمز المميّز للتحقق من وجود معلومات الملف الشخصي للمستخدم في حساب Google في نظامك.
    1. في هذه الحالة، يكون المستخدم قد سجّل الدخول إلى نظامك باستخدام حسابه على Google، ويربط "مساعد Google" هوية المستخدم بحسابه على Google. يمكن للمستخدم مواصلة المحادثة مع المساعد مع ربط حسابه.
    2. وإذا لم يتم ذلك، راجع الخطوة 5.
  5. يمكن للمستخدم إما أ) إنشاء حساب جديد باستخدام معلومات ملفه الشخصي في Google أو ب) تسجيل الدخول إلى نظامك بحساب مختلف. تختلف الخيارات التي يتم عرضها للمستخدم بناءً على ما إذا كنت قد قمت بتمكين أو إيقاف إنشاء الحساب عبر الصوت. إذا اختار المستخدم تسجيل الدخول إلى نظامك باستخدام حساب مختلف، سيبدأ تدفق OAuth القياسي.
  6. بعد أن ينشئ المستخدم حسابًا جديدًا أو يسجّل الدخول باستخدام مقدّم خدمة مختلف، تعرض الخدمة رمز الدخول إلى Google. (إذا كنت تستخدم مسار رمز التفويض، ستعرض الخدمة أيضًا رمزًا مميزًا للتحديث).
  7. يمكن للمستخدم الآن مواصلة المحادثة مع "مساعد Google" وربط حسابه.

تدفقات OAuth وGSI

يستعرض هذا القسم التدفقات المختلفة التي يمكن أن تحدث مع OAuth وGSI. تستعرض هذه المخطّطات البيانية التدفقات التي تحدث من خلال مسار رمز التفويض بدلاً من مسار الرمز الضمني، وتفترض أنّك تستخدم Dialogflow كحلّ طبيعي لفهم اللغة في الإجراء الخاص بك.

يتضمّن كل مسار هذه الخطوات الشائعة بعد استدعاء المستخدم للإجراء الخاص بك:

في الخطوات أعلاه، يتم استدعاء هدف مساعد actions.intent.SIGN_IN من خلال سلسلة سياق مخصّصة لك. يطلب هذا الغرض من المستخدم الإذن للوصول إلى معلومات ملفه الشخصي في Google. بعد موافقة المستخدم، يرسل المساعد طلبًا يحتوي على معلومات الملف الشخصي لـ user@gmail.com.

تختلف التدفقات بعد هذه النقطة بناءً على ما إذا كنت قد أعددت ربط الحساب باستخدام الصوت وما إذا كانت معلومات المستخدم موجودة من قبل في نظامك أم لا. ويتم توضيح كل من هذه التدفقات في الأقسام التالية.

المسارات مع تفعيل إنشاء الحساب الصوتي

يوضّح هذا القسم بالتفصيل خطوات ربط الحساب التي يمكن أن تحدث في حال تفعيل إنشاء الحساب عبر الصوت.

التدفق 1: معلومات المستخدم موجودة في نظامك

في هذه الحالة، يكون المستخدم الذي يتم تمثيله بـ user@gmail.com في الخلفية، وبالتالي تعرض نقطة نهاية تبادل الرمز المميز رمزًا مميزًا للمستخدم. هوية المستخدم في الإجراء الخاص بك مرتبطة الآن بحسابه على Google. يتطابق الطلب الأصلي للمستخدم ("الطلب المعتاد") مع الغرض المخصّص. order_drink. يعالج الرد التلقائي على الويب بعد ذلك تنفيذ الغرض المطابق ويبحث في قاعدة بياناتك لطلب user@gmail.com المعتاد. يمكن للمستخدم بعد ذلك مواصلة محادثته مع المساعد.

المسار 2: معلومات المستخدم غير متوفرة وينشئ المستخدم حسابًا

بسبب تفعيلك لإنشاء الحساب عبر الصوت وعدم توفّر user@gmail.com في الخلفية، سيسأل "مساعد Google" المستخدم عمّا إذا كان يريد تنفيذ أحد الإجراءين التاليَين:

أ) إنشاء حساب جديد على النظام باستخدام معلومات الملف الشخصي في Google، ويمكن إجراء ذلك عبر الصوت

ب) سجّل الدخول إلى النظام باستخدام حساب مختلف

في هذه الحالة، يختار المستخدم إنشاء حساب جديد عبر الصوت. تستدعي Google نقطة نهاية تبادل الرموز المميّزة لخدمتك من خلال طلب إنشاء حساب. يحتوي هذا الطلب على الرمز المميز لمعرّف Google الذي يتضمن المكوّنات اللازمة لإنشاء حساب جديد. يمكنك بعد ذلك استخدام المعلومات من هذا الرمز المميز (اسم المستخدم وعنوان بريده الإلكتروني) لإنشاء حساب للمستخدم.

بعد إنشاء الحساب، تعرض الخدمة رمز الدخول وتُعيد تحميل الرمز المميّز للحساب الذي تم إنشاؤه حديثًا. تم الآن ربط هوية المستخدم في الإجراء الخاص بك بحسابه على Google. يتطابق طلب المستخدم الأصلي ("الطلب المعتاد") مع الغرض المخصص order_drink.. بعد ذلك، يعالج الرد التلقائي على الويب تنفيذ الغرض المطابق ويبحث في قاعدة بياناتك لطلب user@gmail.com المعتاد، وهو غير متوفر حتى الآن لأن المستخدم جديد. عندها يمكن أن يسأل الإجراء الخاص بك المستخدم عما يريد أن يطلبه.

المسار 3: معلومات المستخدم غير موجودة ويسجل المستخدم الدخول باستخدام حساب مختلف

لقد فعّلت إنشاء الحساب عبر الصوت، لذلك يسأل "مساعد Google" المستخدم عمّا إذا كان يريد تنفيذ أحد الإجراءات التالية:

أ) إنشاء حساب جديد على النظام باستخدام معلومات الملف الشخصي في Google، ويمكن إجراء ذلك عبر الصوت

ب) سجّل الدخول إلى النظام باستخدام حساب مختلف

في هذه الحالة، يختار المستخدم تسجيل الدخول باستخدام حساب مختلف، ما يبدأ مسار OAuth العادي. وإذا بدأ المسار على جهاز مخصّص للصوت فقط، تنقل Google عملية التنفيذ إلى هاتف. بعد ذلك، تفتح Google نقطة نهاية التفويض في متصفّح المستخدم، واستنادًا إلى ضبطك، يمكن للمستخدم اختيار ما إذا كان يريد: أ) تسجيل الدخول إلى خدمتك باستخدام حساب حالي لا يستخدم ميزة "تسجيل الدخول بحساب Google" أو ب) إنشاء حساب جديد باستخدام موفّر خدمة مختلف. لمزيد من المعلومات عن مسار OAuth، راجِع دليل مفهوم OAuth.

بعد التحقق من بيانات اعتماد المستخدم، تعرض الخدمة رمز الدخول والرمز المميز لإعادة التحميل إلى Google. تم الآن ربط هوية المستخدم في الإجراء الخاص بك بحساب غير تابع لشركة Google. يتطابق الطلب الأصلي للمستخدم ("الطلب المعتاد") مع الغرض المخصص order_drink.. بعد ذلك، يعالج الرد التلقائي على الويب عملية تنفيذ الغرض المطابق ويبحث في قاعدة بياناتك للطلب المعتاد من user@gmail.com، وهو ما لا يتوفّر بعد لأنّ المستخدم جديد. بعد ذلك يمكن أن يسأل الإجراء الخاص بك المستخدم عن ما يريد أن يطلبه أو يطلب منه إعداد طلبه المعتاد.

التدفق مع إيقاف إنشاء حساب Voice

يوضّح هذا القسم تفاصيل عملية ربط الحساب التي يمكن أن تحدث في حال إيقاف إنشاء الحساب عبر الصوت.

المسار 4: معلومات المستخدم غير موجودة

لم تمكِّن إنشاء الحساب عبر الصوت ولا يكون المستخدم موجودًا في الخلفية، لذا يبدأ تدفق OAuth القياسي. يفتح "مساعد Google" نقطة نهاية التفويض في متصفّح المستخدم (إذا بدأ المسار على جهاز صوتي فقط، تنقل Google عملية التنفيذ إلى جهاز مزوّد بشاشة). يمكن للمستخدم اختيار إما أ) تسجيل الدخول مع مقدّم خدمة مختلف، أو إذا كان مسجّلاً في خدمتك باستخدام حساب مختلف، أو ب) إنشاء حساب جديد مع مقدّم خدمة مختلف. لمزيد من المعلومات عن مسار OAuth، راجِع دليل مفهوم OAuth.

بعد التحقق من بيانات اعتماد المستخدم، تعرض الخدمة رمز الدخول والرمز المميز لإعادة التحميل إلى Google. تم الآن ربط هوية المستخدم في الإجراء الخاص بك بحساب غير تابع لشركة Google. يتطابق الطلب الأصلي للمستخدم ("الطلب المعتاد") مع الغرض المخصص order_drink.. بعد ذلك، يعالج الرد التلقائي على الويب عملية تنفيذ الغرض المطابق ويبحث في قاعدة بياناتك للطلب المعتاد من user@gmail.com، وهو ما لا يتوفّر بعد لأنّ المستخدم جديد. يمكن أن يطلب الإجراء الخاص بك بعد ذلك من المستخدم إعداد طلبه المعتاد.