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

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

检查现有用户账号（检查 intent）

Google 会调用您的令牌交换端点，以验证 Google 用户是否存在于您的系统中。如需了解参数详情，请参阅简化的关联 intent。

实现方案

如需处理所需的 check intent，请执行以下操作：

1. 验证请求：

   • 验证 client_id、client_secret 和 grant_type（必须为 urn:ietf:params:oauth:grant-type:jwt-bearer）。
   • 使用 JWT 验证 中的条件验证 assertion (JWT)。

2. 查找用户：

   • 检查 JWT 中的 Google 账号 ID (sub) 或电子邮件地址是否与数据库中的用户匹配。

3. 回应：

   • 如果找到：返回 HTTP 200 OK，并附带 {"account_found": "true"}。
   • 如果未找到：返回 HTTP 404 Not Found，并附带 {"account_found": "false"}。

处理自动关联（获取 intent）

如果账号存在，Google 会使用 intent=get 调用您的端点以检索令牌。如需了解参数详情，请参阅简化的关联 intent。

实现方案

如需处理所需的 get intent，请执行以下操作：

1. 验证请求：

   • 验证 client_id、client_secret 和 grant_type。
   • 验证 assertion (JWT)。

2. 查找用户：

   • 使用 sub 或 email 声明验证用户是否存在。

3. 回应：

   • 如果成功：在 JSON 响应 (HTTP 200 OK) 中生成并返回 access_token、refresh_token 和 expires_in。
   • 如果关联失败：返回 HTTP 401 Unauthorized，其中包含 {"error": "linking_error"} 和可选的 login_hint，以便回退 到标准 OAuth 关联。

使用“使用 Google 账号登录”功能处理账号创建事宜（创建 intent）

如果您的服务支持账号创建，并且不存在任何账号，Google 会使用 intent=create 调用您的端点，以创建新用户。如需了解参数详情， 请参阅 简化的关联流程 intent。

实现方案

如需处理可选的 create intent，请执行以下操作：

1. 验证请求：

   • 验证 client_id、client_secret 和 grant_type。
   • 验证 assertion (JWT)。

2. 验证用户不存在：

   • 检查您的数据库中是否已存在 sub 或 email。
   • 如果用户存在，请返回 HTTP 401 Unauthorized，并使用 {"error": "linking_error", "login_hint": "USER_EMAIL"}强制 回退到 OAuth 关联流程。

3. 创建账号：

   • 使用 JWT 中的 sub、email、name 和 picture 声明创建新的用户记录。

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 Playground 工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击配置 settings 以打开“OAuth 2.0 配置”窗口。
2. 在 OAuth flow（OAuth 流程）字段中，选择 Client-side（客户端）。
3. 在 OAuth Endpoints 字段中，选择 Custom。
4. 在相应字段中指定您的 OAuth 2.0 端点以及您分配给 Google 的客户端 ID。
5. 在第 1 步部分中，请勿选择任何 Google 范围。请将此字段留空，或输入适用于您服务器的范围（如果您不使用 OAuth 范围，则输入任意字符串）。完成后，点击 Authorize APIs。
6. 在第 2 步和第 3 步部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击使用 Google 账号登录按钮。
2. 选择您要关联的账号。
3. 输入服务 ID。
4. （可选）输入您将请求访问的一个或多个范围。
5. 点击开始演示。
6. 当系统提示时，请确认您可以同意或拒绝关联请求。
7. 确认您已重定向到相应平台。