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

نظرة عامة

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

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

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

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

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

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

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

الشكل 2. تسلسل الأحداث في مسار الربط السلس

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

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

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

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

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

ملاحظة: يجب تنفيذ هذه الأهداف في نقطة نهاية تبادل الرموز المميزة نفسها التي أنشأتها لعملية ربط OAuth الأساسي. لا تنشئ نقطة نهاية مختلفة للتعامل مع هذه النوايا.

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

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

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 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 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 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 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 المعتمَدة.

   نقطة أساسية: أضِف كلاً من http://localhost وhttp://localhost:<port_number> إلى الحقل مصادر JavaScript المسموح بها لإجراء اختبارات محلية أو لأغراض التطوير.

   ملاحظة: يبدو معرّف العميل على النحو التالي:

   1234567890-abc123def456.apps.googleusercontent.com
   

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

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