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

نظرة عامة

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

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

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

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

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

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

المستخدم تطبيق Google / الخادم الرمز المميّز نقطة تبادل الرموز المميزة واجهة برمجة التطبيقات 1. يبدأ المستخدم عملية الربط 2. طلب تسجيل الدخول باستخدام حساب Google 3. تسجيل الدخول باستخدام Google 4. التحقّق من الغرض (تأكيد JWT) 5. account_found: true/false في حال العثور على حساب: 6. الحصول على الغرض في حال عدم العثور على حساب: 6. إنشاء الغرض 7. access_token وrefresh_token 8. رموز المستخدمين في المتجر 9. الوصول إلى موارد المستخدم
الشكل 2. تسلسل الأحداث في مسار الربط المبسّط

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

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

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

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

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

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

  1. هل لدى المستخدم حساب في نظام المصادقة؟ (يقرّر المستخدم من خلال اختيار "نعم" أو "لا")
    1. نعم : هل يستخدم المستخدم عنوان البريد الإلكتروني المرتبط بحسابه على Google لتسجيل الدخول إلى منصتك؟ (يقرّر المستخدم ذلك من خلال اختيار "نعم" أو "لا")
      1. YES : Does the user have a matching account in your authentication system? (يتم استدعاء نية check للتأكيد)
        1. نعم : يتم استدعاء get intent ويتم ربط الحساب إذا تم عرض النتيجة بنجاح عند استدعاء get intent.
        2. لا : إنشاء حساب جديد؟ (يقرّر المستخدم ذلك من خلال اختيار "نعم" أو "لا"، ولا ينطبق ذلك إلا إذا كانت خدمتك تتيح إنشاء الحسابات)
          1. نعم : يتم استدعاء create intent ويتم ربط الحساب إذا تم عرض intent الخاص بالإنشاء بنجاح.
          2. لا : يتم تفعيل عملية الربط باستخدام OAuth، ويتم توجيه المستخدم إلى المتصفّح، ويُمنح المستخدم خيار الربط بعنوان بريد إلكتروني مختلف.
      2. لا : يتم تفعيل مسار ربط حساب OAuth، ويتم توجيه المستخدم إلى المتصفّح، ويُمنح المستخدم خيار الربط بعنوان بريد إلكتروني مختلف.
    2. لا : هل لدى المستخدم حساب مطابق في نظام المصادقة؟ (يتم استدعاء نية check للتأكيد)
      1. نعم : يتم استدعاء get intent ويتم ربط الحساب إذا تم عرض get intent بنجاح.
      2. NO : إذا كانت خدمتك تتيح إنشاء الحسابات، سيتم استدعاء create intent وسيتم ربط الحساب إذا تم عرض create intent بنجاح. إذا لم يكن إنشاء الحساب متاحًا، يجب أن تعرض نقطة النهاية الخطأ HTTP 401 linking_error لتفعيل مسار الربط الاحتياطي باستخدام OAuth.

وصفة التنفيذ

يجب أن تنفّذ نقطة نهاية تبادل الرموز المميزة الغرضَين المطلوبَين 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. انقر على الإعداد لفتح نافذة "إعدادات 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. تأكَّد من إعادة توجيهك إلى منصتك.