عملية ربط مبسطة باستخدام OAuth و"تسجيل الدخول باستخدام حساب Google"

نظرة عامة

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

لإجراء عملية ربط الحساب باستخدام OAuth و"تسجيل الدخول باستخدام حساب Google"، اتّبِع الخطوات العامة التالية:

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

الشكل 1 ربط الحسابات على هاتف المستخدم باستخدام ميزة "الربط السلس"

الربط السلس: مسار OAuth + "تسجيل الدخول باستخدام حساب Google"

يوضّح مخطط التسلسل التالي تفاصيل التفاعلات بين المستخدم وGoogle ونقطة نهاية تبادل الرموز المميزة في ميزة "الربط السلس".

الأدوار والمسؤوليات

يوضّح الجدول التالي أدوار ومسؤوليات الجهات الفاعلة في مسار الربط المبسّط.

الجهة الفاعلة / المكوّن	دور قائمة العناوين العمومية	المسؤوليات
تطبيق / خادم Google	عميل OAuth	الحصول على موافقة المستخدم على خدمة "تسجيل الدخول باستخدام حساب Google"، وتمرير تأكيدات الهوية (JWT) إلى الخادم، وتخزين الرموز المميزة الناتجة بأمان
نقطة نهاية تبادل الرموز المميزة	موفِّر الهوية / خادم التفويض	تتحقّق هذه الخدمة من صحة تأكيدات الهوية، وتبحث عن حسابات حالية، وتتعامل مع نوايا ربط الحسابات (check وget وcreate)، وتصدر رموزًا مميّزة استنادًا إلى النوايا المطلوبة.
واجهة برمجة التطبيقات الخاصة بالخدمة	خادم الموارد	توفير إمكانية الوصول إلى بيانات المستخدم عند تقديم رمز دخول صالح

متطلبات ميزة "الربط السلس"

• نفِّذ مسار ربط الحسابات الأساسي باستخدام OAuth. يجب أن تتيح خدمتك نقاط نهاية التفويض وتبادل الرموز المميزة المتوافقة مع بروتوكول OAuth 2.0.
• يجب أن تتوافق نقطة نهاية تبادل الرموز المميزة مع تأكيدات رمز JSON المميّز للويب (JWT) وأن تنفّذ الأهداف check وcreate وget.

• تسجيل معرّف عميل Google API

منطق اتخاذ القرار بشأن الربط المبسّط

تحدّد المنطق التالي كيفية طلب الأهداف أثناء مسار "ربط الحسابات بسلاسة":

1. هل لدى المستخدم حساب في نظام المصادقة؟ (يقرّر المستخدم ذلك من خلال اختيار "نعم" أو "لا")
   1. نعم : هل يستخدم المستخدم عنوان البريد الإلكتروني المرتبط بحساب Google لتسجيل الدخول إلى منصتك؟ (يقرّر المستخدم ذلك من خلال اختيار "نعم" أو "لا")
      1. نعم : هل لدى المستخدم حساب مطابق في نظام المصادقة؟ (يتم الاتصال بالرقم check intent للتأكيد)
         1. YES : يتم الاتصال بـ get intent ويتم ربط الحساب إذا تم عرض نتيجة get intent بنجاح.
         2. لا : إنشاء حساب جديد؟ (يقرّر المستخدم ذلك من خلال اختيار "نعم" أو "لا")
            1. نعم : يتم استدعاء create intent ويتم ربط الحساب إذا تم عرض نتيجة إنشاء الطلب بنجاح.
            2. لا : يتم بدء عملية الربط باستخدام OAuth، ويتم توجيه المستخدم إلى المتصفّح، ويُمنح المستخدم خيار الربط بعنوان بريد إلكتروني مختلف.
      2. لا : يتم تفعيل مسار الربط باستخدام OAuth، ويتم توجيه المستخدم إلى المتصفّح الخاص به، ويُمنح المستخدم خيار الربط بعنوان بريد إلكتروني مختلف.
   2. لا : هل لدى المستخدم حساب مطابق في نظام المصادقة؟ (يتم الاتصال بالرقم check intent للتأكيد)
      1. YES : يتم الاتصال بـ get intent ويتم ربط الحساب إذا تم عرض نتيجة get intent بنجاح.
      2. NO : يتم استدعاء create intent ويتم ربط الحساب إذا تم عرض نتيجة إنشاء النية بنجاح.

وصفة التنفيذ

يجب أن تنفّذ نقطة نهاية تبادل الرموز المميزة الأهداف check وget وcreate لتوفير ميزة "الربط السلس".

اتّبِع الخطوات التالية للتعامل مع النوايا المختلفة:

التحقّق من وجود حساب مستخدم حالي (التحقّق من الغرض)

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

وصفة التنفيذ

للتعامل مع الغرض check ، يُرجى تنفيذ الإجراءات التالية:

1. التحقّق من صحة الطلب:

   • يُرجى التحقّق من client_id وclient_secret وgrant_type (يجب أن يكون urn:ietf:params:oauth:grant-type:jwt-bearer).
   • يُرجى التحقّق من صحة assertion (رمز JWT) باستخدام المعايير الواردة في التحقّق من صحة رمز JWT.

2. البحث عن المستخدم:

   • يُرجى التحقّق مما إذا كان رقم تعريف حساب Google (sub) أو عنوان البريد الإلكتروني في رمز JWT يطابق مستخدمًا في قاعدة بياناتك.

3. الردّ:

   • في حال العثور على حساب: يتم عرض رمز HTTP 200 OK مع {"account_found": "true"}.
   • في حال عدم العثور على حساب: يتم عرض رمز HTTP 404 Not Found مع {"account_found": "false"}.

التعامل مع الربط التلقائي (الحصول على الغرض)

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

وصفة التنفيذ

للتعامل مع الغرض get، يُرجى اتّخاذ الإجراءات التالية:

1. التحقّق من صحة الطلب:

   • التحقّق من client_id وclient_secret وgrant_type
   • التحقّق من صحة assertion (رمز JWT)

2. البحث عن المستخدم:

   • التحقّق من وجود المستخدم باستخدام طلب sub أو email

3. الردّ:

   • في حال نجاح العملية: إنشاء access_token وrefresh_token وexpires_in وعرضها في ردّ بتنسيق JSON (HTTP 200 OK)
   • في حال تعذُّر الربط: عرض HTTP 401 Unauthorized مع {"error": "linking_error"} وlogin_hint اختياري للرجوع إلى الربط العادي باستخدام OAuth

التعامل مع إنشاء الحسابات باستخدام ميزة "تسجيل الدخول باستخدام حساب Google" (نية الإنشاء)

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

وصفة التنفيذ

للتعامل مع نية create، يُرجى اتّخاذ الإجراءات التالية:

1. التحقّق من الطلب:

   • التحقّق من client_id وclient_secret وgrant_type
   • التحقّق من assertion (رمز JWT)

2. التحقّق من عدم وجود المستخدم:

   • التحقّق مما إذا كان sub أو email موجودًا من قبل في قاعدة البيانات
   • إذا كان المستخدم موجودًا: يتم عرض الخطأ HTTP 401 Unauthorized مع {"error": "linking_error", "login_hint": "USER_EMAIL"} لفرض الرجوع إلى الربط باستخدام بروتوكول OAuth.

3. إنشاء حساب:

   • استخدام طلبات sub وemail وname وpicture من رمز JWT لإنشاء سجلّ مستخدم جديد

4. الردّ:

   • إنشاء الرموز وإرجاعها في استجابة JSON (HTTP 200 OK)

الحصول على معرّف عميل Google API

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

1. انتقِل إلى صفحة العملاء.

2. أنشئ مشروعًا على Google APIs أو اختَر مشروعًا حاليًا.

   إذا لم يكن مشروعك يتضمّن معرّف عميل من نوع تطبيق الويب، انقر على إنشاء عميل لإنشاء معرّف. تأكَّد من تضمين نطاق موقعك الإلكتروني في مربّع مصادر JavaScript المعتمَدة. عند إجراء اختبارات أو عمليات تطوير محلية، يجب إضافة كل من http://localhost وhttp://localhost:<port_number> إلى حقل مصادر JavaScript المعتمَدة.

التحقّق من صحة عملية التنفيذ

يمكنك التحقّق من صحة التنفيذ باستخدام أداة مساحة بروتوكول OAuth 2.0.

في الأداة، اتّبِع الخطوات التالية:

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

يمكنك التحقّق من صحة عملية التنفيذ باستخدام أداة عرض توضيحي لربط حساب Google.

في الأداة، اتّبِع الخطوات التالية:

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