ربط الحساب باستخدام بروتوكول OAuth

يتوافق نوع ربط حساب OAuth مع مسارَي OAuth 2.0 وفقًا للمعيار المتّبع في المجال، وهما مسار الربط الضمني ومسار رمز التفويض.

在隐式代码流程中，Google 会在用户浏览器中打开您的授权端点。成功登录后，系统会向 Google 返回长期访问令牌。现在，从 Google 助理向你的 Action 发送的每个请求中都包含此访问令牌。

在授权代码流程中，您需要两个端点：

• 授权端点，该端点负责向尚未登录的用户显示登录界面，并以短期授权代码的形式记录所请求的访问。
• 令牌交换端点，负责两种类型的交换：
  1. 将授权代码交换为长期刷新令牌和短期访问令牌。用户完成帐号关联流程后，系统会进行这种交换。
  2. 将长期刷新令牌换成短期访问令牌。Google 需要新访问令牌时，由于此令牌已过期，因此会进行此交换。

虽然隐式代码流程的实现更简单，但 Google 建议通过隐式流程发出的访问令牌永远不会过期，因为将令牌过期与隐式流程一起使用会强制用户再次关联其帐号。如果出于安全考虑需要令牌到期，强烈建议您考虑使用身份验证代码流程。

تنفيذ عملية ربط حساب OAuth

ضبط إعدادات المشروع

لضبط مشروعك لاستخدام ميزة ربط الحسابات عبر OAuth، اتّبِع الخطوات التالية:

1. افتح Actions Console واختَر المشروع الذي تريد استخدامه.
2. انقر على علامة التبويب تطوير واختَر ربط الحساب.
3. فعِّل مفتاح التبديل بجانب ربط الحساب.
4. في قسم إنشاء الحساب، اختَر لا، أريد فقط السماح بإنشاء الحساب على موقعي الإلكتروني.

5. في نوع الربط، اختَر OAuth ورمز التفويض.

   

6. في معلومات العميل:

   • عيِّن قيمة لمعرّف العميل الصادر عن "إجراءات على Google" لتحديد الطلبات الواردة من Google.
   • دوِّن قيمة معرّف العميل الذي أصدرته Google لإجراءاتك.
   • أدرِج عناوين URL لنقاط نهاية التفويض وتبادل الرموز المميزة.

6. انقر على حفظ.

تنفيذ خادم OAuth

يتألف تنفيذ خادم OAuth 2.0 لتدفق رمز التفويض من: نقطتَي النهاية، اللتين تتيحهما خدمتك باستخدام بروتوكول HTTPS. نقطة النهاية الأولى هي نقطة نهاية التفويض، وهي المسئولة عن إيجاد أو الحصول على موافقة المستخدمين على الوصول إلى البيانات. تعرض نقطة نهاية التفويض تسجيل دخول واجهة مستخدم للمستخدمين الذين لم يسجّلوا الدخول من قبل وتسجِّل الموافقة على طلب الوصول. نقطة النهاية الثانية هي نقطة نهاية تبادل الرموز، وهي يُستخدم للحصول على سلاسل مشفّرة تسمى الرموز المميزة التي تمنح مستخدم الإجراء للدخول إلى خدمتك.

عندما يحتاج الإجراء الخاص بك إلى استدعاء إحدى واجهات برمجة التطبيقات الخاصة بخدمتك، تستخدم Google هذه واجهات برمجة التطبيقات. نقاط النهاية معًا للحصول على إذن من المستخدمين لاستدعاء واجهات برمجة التطبيقات هذه على بالنيابة عنك.

في ما يلي الخطوات التي يجب اتّباعها لجلسة مسار رمز مصادقة OAuth 2.0 التي بدأتها Google:

1. تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. إذا لم يكن التدفق على جهاز الصوت فقط لتنفيذ إجراء، فستنقل Google إلى الهاتف.

2. يسجِّل المستخدم الدخول (إذا لم يكن مسجّلاً الدخول)، ويمنح Google الإذن الوصول إلى بياناتهم باستخدام واجهة برمجة التطبيقات إذا لم يسبق لهم منحها الإذن بذلك

3. تنشئ الخدمة رمز تفويض وترسله إلى Google من خلال إعادة توجيه متصفح المستخدم إلى Google مرة أخرى باستخدام رمز التفويض المرفق بالطلب.

4. ترسل Google رمز التفويض إلى نقطة نهاية تبادل الرموز المميّزة، يتحقق من صحة الرمز ويعرض رمز دخول الرمز المميّز لإعادة التحميل رمز الدخول هو رمز مميز طويل الأجل يمكن لخدمتك كبيانات اعتماد للوصول إلى واجهات برمجة التطبيقات. الرمز المميز لإعادة التحميل طويل الأمد هو رمز مميز يمكن أن تخزّنه Google وتستخدمه للحصول على رموز دخول جديدة عند تنتهي صلاحيته.

5. بعد أن يكمل المستخدم عملية ربط الحساب، مُرسَل من "مساعد Google" إلى الردّ التلقائي على الويب الخاص بالتنفيذ يحتوي على .

التعامل مع طلبات التفويض

عندما يحتاج الإجراء الخاص بك إلى ربط الحساب عبر رمز تفويض OAuth 2.0 ترسل Google المستخدم إلى نقطة نهاية التفويض من خلال طلب يتضمن المعلَمات التالية:

على سبيل المثال، إذا كانت نقطة نهاية التفويض متاحة على https://myservice.example.com/auth، قد يبدو الطلب كما يلي:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code

لكي تعالج نقطة نهاية التفويض طلبات تسجيل الدخول، عليك اتّباع الخطوات التالية:

1. يُرجى التأكّد من أنّ client_id يتطابق مع معرّف عميل Google الذي سجّلت باستخدامه. Google، وأن redirect_uri يتطابق مع عنوان URL لإعادة التوجيه الذي تقدمه Google على خدمتك. تُعدّ عمليات التحقق هذه مهمة لمنع منح إمكانية الوصول إلى تطبيقات العميل غير المقصودة أو التي تم إعدادها بشكلٍ غير صحيح.

   إذا كنت تسمح بمسارات OAuth 2.0 متعددة، تأكَّد أيضًا من أنّ تم code ميزة response_type.

2. تحقق مما إذا كان المستخدم قد سجّل الدخول إلى خدمتك. إذا لم يسجّل المستخدم الدخول، لإكمال عملية تسجيل الدخول أو الاشتراك في الخدمة.

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

4. تأكَّد من أنّ عنوان URL الذي تحدّده المَعلمة redirect_uri بالشكل التالي:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

   YOUR_PROJECT_ID هو رقم التعريف الوارد في صفحة إعدادات المشروع. من وحدة التحكم في المهام.

5. إعادة توجيه متصفح المستخدم إلى عنوان URL المحدد من خلال مَعلمة redirect_uri. قم بتضمين رمز التفويض الذي قمت التي تم إنشاؤها للتو وقيمة الحالة الأصلية غير المعدلة عند إعادة التوجيه من خلال إلحاق المعلمتَين code وstate. فيما يلي مثال لعنوان URL الناتج:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

التعامل مع طلبات تبادل الرموز المميّزة

تكون نقطة نهاية تبادل الرموز المميّزة لخدمتك مسؤولة عن نوعَين من الرموز المميّزة التبادلات:

• استبدال رموز التفويض برموز الدخول ورموز إعادة التحميل
• الرموز المميزة لإعادة تحميل Exchange لرموز الدخول

تشمل طلبات تبادل الرموز المميّزة المَعلمات التالية:

استبدال رموز التفويض برموز الدخول ورموز إعادة التحميل

بعد أن يسجِّل المستخدم دخوله وترسِل نقطة نهاية التفويض تفويضًا قصير الأجل رمزًا إلى Google، سترسل Google طلبًا إلى نقطة نهاية تبادل الرموز المميّزة رمز التفويض لرمز الدخول ورمز التحديث.

بالنسبة إلى هذه الطلبات، تكون قيمة grant_type هي authorization_code، والقيمة من code هي قيمة رمز التفويض الذي منحته سابقًا إلى Google. في ما يلي مثال على طلب استبدال رمز تفويض لحساب رمز الدخول والرمز المميز للتحديث:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

لتبادل رموز التفويض لرمز دخول ورمز مميز لإعادة التحميل، يجب تستجيب نقطة نهاية تبادل الرموز المميّزة لطلبات POST التي يتم فيها تنفيذ الخطوات التالية:

1. تحقَّق من أنّ client_id يحدّد مصدر الطلب على أنّه مصدر معتمَد. وأن client_secret تتطابق مع القيمة المتوقعة.
2. تحقَّق مما يلي:
   • رمز التفويض صالح وغير منتهي الصلاحية، والعميل يتطابق المعرّف المحدّد في الطلب مع معرِّف العميل المرتبط رمز التفويض.
   • عنوان URL الذي حدَّدته المَعلمة redirect_uri متطابق إلى القيمة المستخدمة في طلب التفويض الأولي.
3. إذا لم تتمكن من التحقق من جميع المعايير المذكورة أعلاه، فاعرض HTTP 400 خطأ "طلب غير صالح" مع {"error": "invalid_grant"} كنص الرسالة.
4. بخلاف ذلك، يمكنك إعادة تحميل الصفحة باستخدام رقم تعريف المستخدِم من رمز التفويض. ورمز الدخول. يمكن أن تكون هذه الرموز المميزة أي قيمة سلسلة، ولكن يجب أن يمثل المستخدم والعميل الذي لديه الرمز المميز بشكل فريد، يمكن تخمينه. بالنسبة إلى رموز الدخول، سجِّل أيضًا وقت انتهاء صلاحية الرمز (عادةً بعد ساعة من إصدار الرمز المميّز). عدم انتهاء صلاحية الرموز المميّزة لإعادة التحميل
5. عرض كائن JSON التالي في نص استجابة HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

تخزِّن Google رمز الدخول والرمز المميّز لإعادة التحميل للمستخدم وتسجِّل انتهاء صلاحية رمز الدخول. عند انتهاء صلاحية رمز الدخول، تستخدم Google عملية إعادة التحميل للحصول على رمز دخول جديد من نقطة نهاية تبادل الرموز المميّزة.

الرموز المميزة لإعادة تحميل Exchange لرموز الدخول

عند انتهاء صلاحية رمز الدخول، ترسل Google طلبًا إلى نقطة نهاية تبادل الرمز المميّز. لاستبدال رمز مميز لإعادة التحميل برمز دخول جديد.

بالنسبة إلى هذه الطلبات، تكون قيمة grant_type هي refresh_token، والقيمة لـ refresh_token هي قيمة الرمز المميز لإعادة التحميل الذي منحته سابقًا إلى Google. فيما يلي مثال على طلب استبدال رمز مميّز لإعادة التحميل رمز الدخول:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

لاستبدال رمز مميز لإعادة التحميل برمز دخول، يجب أن تكون نقطة نهاية تبادل الرموز المميّزة يستجيب لطلبات POST التي يتم فيها تنفيذ الخطوات التالية:

1. تأكَّد من أنّ السمة client_id تعرِّف مصدر الطلب على أنّه Google، وأن client_secret تتطابق مع
2. تأكَّد من صلاحية الرمز المميّز لإعادة التحميل ومن أنّ معرِّف العميل المحدَّد في يتطابق الطلب مع معرِّف العميل المرتبط بالرمز المميّز لإعادة التحميل.
3. إذا لم تتمكن من التحقق من جميع المعايير المذكورة أعلاه، فاعرض HTTP 400 خطأ "طلب غير صالح" مع {"error": "invalid_grant"} كنص الرسالة.
4. بخلاف ذلك، يمكنك استخدام رقم تعريف المستخدم من الرمز المميّز لإعادة التحميل لإنشاء إذن وصول. الرمز المميز. يمكن أن تكون هذه الرموز المميزة أي قيمة سلسلة، ولكن يجب أن تمثل المستخدم والعميل المرتبط بالرمز المميز، ويجب ألا يتمكنا من تخمينهما. بالنسبة إلى رموز الدخول، سجِّل أيضًا وقت انتهاء صلاحية الرمز (عادةً بعد ساعة من إصدار الرمز المميّز).
5. عرض كائن JSON التالي في نص HTTPS الرد:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

تصميم واجهة المستخدم الصوتية لمسار المصادقة

التحقّق من إثبات هوية المستخدم وبدء عملية ربط الحساب

1. افتح مشروعك في Actions Builder في Actions Console.
2. أنشئ مشهدًا جديدًا لبدء ربط الحساب في تطبيقك:
   1. انقر على المشاهد.
   2. انقر على رمز إضافة (+) لإضافة مشهد جديد.
3. في المشهد الذي تم إنشاؤه حديثًا، انقر على رمز الإضافة add الشروط.
4. أضِف شرطًا يتحقّق مما إذا كان المستخدم المرتبط بالمحادثة مستخدمًا تم التحقّق منه. إذا لم تنجح عملية التحقّق، لن تتمكّن مهمتك من ربط الحساب أثناء المحادثة، ويجب أن تعود إلى توفير إمكانية الوصول إلى الوظائف التي لا تتطلّب ربط الحساب.
   1. في الحقل Enter new expression ضِمن الشرط، أدخِل المنطق التالي: user.verificationStatus != "VERIFIED"
   2. ضمن الانتقال، اختَر مشهدًا لا يتطلّب ربط الحساب أو مشهدًا يشكّل نقطة دخول إلى الوظائف المتاحة للضيوف فقط.

1. انقر على رمز الإضافة add في الشروط.
2. أضِف شرطًا لتفعيل مسار ربط الحساب إذا لم يكن لدى المستخدم هوية مرتبطة.
   1. في الحقل Enter new expression ضِمن الشرط، أدخِل المنطق التالي: user.verificationStatus == "VERIFIED"
   2. ضمن الانتقال، اختَر مشهد نظام ربط الحساب.
   3. انقر على حفظ.

بعد الحفظ، تتم إضافة مشهد جديد لنظام ربط الحسابات باسم <SceneName>_AccountLinking إلى مشروعك.

تخصيص مشهد ربط الحساب

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

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

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

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

التعامل مع طلبات الوصول إلى البيانات

إذا كان طلب "مساعد Google" يتضمّن رمز دخول، عليك أولاً التأكّد من أنّ رمز الدخول صالح (ولم تنتهِ صلاحيته)، ثم استرداد حساب المستخدم المرتبط من قاعدة البيانات.