عملية ربط مبسطة باستخدام 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. نعم : هل لدى المستخدم حساب مطابق في نظام المصادقة؟ (يتم الاتصال بالرقم 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"}.

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

إذا كان الحساب موجودًا، تتصل 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 المعتمَدة.

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

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

  1. Click Configuration to open the OAuth 2.0 Configuration window.
  2. In the OAuth flow field, select Client-side.
  3. In the OAuth Endpoints field, select Custom.
  4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
  5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
  6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

  1. Click the Sign in with Google button.
  2. Choose the account you'd like to link.
  3. Enter the service ID.
  4. Optionally enter one or more scopes that you will request access for.
  5. Click Start Demo.
  6. When prompted, confirm that you may consent and deny the linking request.
  7. Confirm that you are redirected to your platform.