دليل مفهوم OAuth (Dialogflow)

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

بروتوكول OAuth هو الحل المقترَح لربط الحساب في حال انطباق ما يلي:

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

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

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

قبل القراءة عن آلية عمل OAuth، تعرَّف على البنود التالية:

• هدف المساعد في تسجيل الدخول إلى الحساب: هو هدف المساعد الذي تطلبه لطلب عملية ربط للحساب من "مساعد Google". لمزيد من المعلومات، اطّلع على تسجيل الدخول إلى الحساب.
  • سلسلة السياق: سلسلة مخصّصة تضيفها إلى الغرض من مساعد تسجيل الدخول إلى الحساب لإعلام المستخدم بسبب حاجته إلى ربط حسابه.

• مسار رمز التفويض: خلال مسار OAuth 2.0 هذا، تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. إذا تم تسجيل الدخول بنجاح، تنشئ الخدمة رمز تفويض وتعيده إلى Google. ترسل Google رمز التفويض هذا إلى نقطة نهاية تبادل الرموز المميّزة، التي تتحقّق من صحة الرمز وتعرض رمز الدخول والرمز المميّز لإعادة التحميل.

  يتطلب هذا التدفق نقطتَي نهاية:

  • نقطة نهاية التفويض: نقطة النهاية المسؤولة عن إيجاد موافقة المستخدمين على الوصول إلى البيانات أو الحصول عليها. تنفّذ نقطة النهاية هذه ما يلي:
    1. يعرض واجهة المستخدم لتسجيل الدخول للمستخدمين الذين لم يسبق لهم تسجيل الدخول.
    2. يسجل هذا الحقل الموافقة على الوصول المطلوب في شكل رمز تفويض قصير الأجل.
  • نقطة نهاية تبادل الرموز المميّزة: تُستخدَم نقطة النهاية هذه للحصول على سلاسل مشفَّرة تُعرف باسم الرموز المميّزة والتي تسمح لمستخدم "الإجراء" بالوصول إلى خدمتك. نقطة النهاية هذه مسؤولة عن نوعَين من التبادلات:
    1. تتبادل رمز التفويض مع رمز مميّز طويل الأمد لإعادة التحميل ورمز دخول قصير الأجل. يحدث هذا التبادل عندما يمر المستخدم بعملية ربط الحساب.
    2. تتبادل الرمز المميّز لإعادة التحميل طويل الأمد مع رمز دخول قصير الأجل. يحدث التبادل هذا عندما تحتاج Google إلى رمز دخول جديد بسبب انتهاء صلاحيته.

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

• رمز الدخول: رمز مميز يفوّض خدمتك بالوصول إلى أجزاء من بيانات المستخدم. ترتبط رموز الدخول بكل مستخدم فردي ويجب أن تكون غير قابلة للتخمين.

• رمز إعادة التحميل المميّز: رمز مميّز يتم استبداله برمز دخول جديد بعد انتهاء صلاحية رمز دخول قصير الأجل.

آلية العمل

يصف هذا القسم التدفق العام لرمز تفويض OAuth والتدفقات الضمنية. يصف القسم التالي، تدفقات OAuth، التدفقات المختلفة التي يمكن أن تحدث مع OAuth.

يمكن تلخيص مسار رمز التفويض كما يلي:

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

يمكن تلخيص تدفق التعليمات البرمجية الضمنية على النحو التالي:

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

يكون مسار رمز التفويض الأساسي على النحو التالي:

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

مسارات OAuth

يستعرض هذا القسم التدفقات المختلفة التي يمكن أن تحدث مع OAuth.

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

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

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

المسار 1: تسجيل دخول المستخدم من خلال تدفق ضمني

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

المسار 2: تسجيل دخول المستخدم باستخدام مسار رمز التفويض

بعد تسجيل دخول المستخدم والتحقق من بيانات اعتماده، تنشئ الخدمة رمز تفويض وتعيده إلى Google.

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