عملية ربط مبسطة باستخدام 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 وget، بالإضافة إلى الغرض create بشكل اختياري.

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

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

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

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 لتوفير ميزة "الربط السلس".

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

Check for an existing user account (check intent)

Google calls your token exchange endpoint to verify if the Google user exists in your system. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the required check intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type (must be urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Validate the assertion (JWT) using the criteria in JWT Validation.

2. Lookup user:

   • Check if the Google Account ID (sub) or email address in the JWT matches a user in your database.

3. Respond:

   • If found: Return HTTP 200 OK with {"account_found": "true"}.
   • If not found: Return HTTP 404 Not Found with {"account_found": "false"}.

Handle automatic linking (get intent)

If the account exists, Google calls your endpoint with intent=get to retrieve tokens. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the required get intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Lookup user:

   • Verify the user exists using the sub or email claim.

3. Respond:

   • If successful: Generate and return access_token, refresh_token, and expires_in in a JSON response (HTTP 200 OK).
   • If linking fails: Return HTTP 401 Unauthorized with {"error": "linking_error"} and an optional login_hint to fall back to standard OAuth linking.

Handle account creation using Sign in with Google (create intent)

If your service supports account creation and no account exists, Google calls your endpoint with intent=create to create a new user. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the optional create intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Verify user does not exist:

   • Check if the sub or email is already in your database.
   • If the user does exist: Return HTTP 401 Unauthorized with {"error": "linking_error", "login_hint": "USER_EMAIL"} to force fallback to OAuth linking.

3. Create account:

   • Use the sub, email, name, and picture claims from the JWT to create a new user record.

4. Respond:

   • Generate and return tokens in a JSON response (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. تأكَّد من إعادة توجيهك إلى منصتك.