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

يدعم نوع ربط OAuth تدفقين من تدفقات OAuth 2.0 المتوافقة مع المعيار المتّبع في المجال، وهما تدفقات الرموز الضمنية والتفويض.

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

في مسار رمز التفويض، ستحتاج إلى نقطتَي نهاية:

• نقطة نهاية التفويض المسؤولة عن تقديم واجهة مستخدم تسجيل الدخول للمستخدمين الذين لم يسجّلوا الدخول وتسجيل الموافقة على الوصول المطلوب في شكل رمز تفويض قصير الأجل.
• نقطة نهاية تبادل الرموز المسؤولة عن نوعَين من عمليات التبادل:
  1. تبادل رمز التفويض لرمز مميز لإعادة التحميل طويل الأجل ورمز دخول قصير الأجل وتتم عملية التبادل هذه عندما يجري المستخدم عملية ربط الحساب.
  2. لتبادل رمز مميز لإعادة التحميل طويل الأمد لرمز دخول قصير الأجل وتتم عملية التبادل هذه عندما تحتاج Google إلى رمز دخول جديد لأنّ الرمز الذي انتهت صلاحيته.

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

ملاحظة: يُرجى اختيار مسار OAuth 2.0 الذي تريد تنفيذه. إذا لزم الأمر، تتم إعادة تحميل محتوى هذا الدليل لتتلاءم مع الخيار الذي تريده.

رمز المصادقة تدفق ضمني

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

ملاحظة: في حال تنفيذ عملية ربط الحساب بهدف معالجة المعلومات المالية، يُرجى العِلم أنّه قد يتم تطبيق سياسات إضافية على الإجراء الخاص بك. قد تستغرق مراجعة إجراء مع ربط الحساب للمعلومات المالية فترةً تصل إلى ستة أسابيع، لذا ضع هذا الوقت في الاعتبار عند التخطيط لجدول الإصدار الخاص بك. لتيسير عملية المراجعة، احرص على الالتزام بسياسات الخدمات المالية قبل إرسال الإجراء الخاص بك للمراجعة.

ضبط المشروع

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

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

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

   

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

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

ملاحظة: إذا كنت تريد إرسال معرّف العميل والسر كسلسلة base64 مرمّزة، انقر على سهم القائمة المنسدلة بجانب إعداد عميلك (اختياري) وضَع علامة في المربّع Google لنقل معرِّف العميل والسر عبر عنوان المصادقة الأساسي HTTP.

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

تنفيذ خادم OAuth

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

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

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

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

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

   ملاحظة: يجب الإشارة إلى أنّ حساب المستخدم مرتبط بـ Google، وليس بمنتج معيّن من Google، مثل Google Home أو "مساعد Google".

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

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

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

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

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

مَعلمات نقطة نهاية التفويض
client_id	معرِّف عميل Google الذي سجَّلته في Google.
redirect_uri	عنوان URL الذي ترسل إليه الرد على هذا الطلب.
state	يشير ذلك المصطلح إلى قيمة مسك الدفاتر التي يتم إرجاعها إلى Google بدون تغيير في معرّف الموارد المنتظم (URI) لإعادة التوجيه.
scope	اختياري: مجموعة من سلاسل النطاقات مفصولة بمسافات والتي تحدّد البيانات التي تطلب Google إذنًا لها.
response_type	السلسلة code.

على سبيل المثال، إذا كانت نقطة نهاية التفويض متاحة على 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 المتعددة، تأكَّد أيضًا من أنّ response_type هي code.

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

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

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

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

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

مَعلمات نقاط نهاية تبادل الرموز المميّزة
client_id	سلسلة تحدد مصدر الطلب على أنه Google ويجب تسجيل هذه السلسلة في نظامك باعتبارها معرّف Google الفريد.
client_secret	سلسلة سرية سجّلتها لدى Google للخدمة التي تقدّمها.
grant_type	نوع الرمز المميّز الذي يتم تبادله. إما authorization_code أو refresh_token.
code	عند grant_type=authorization_code، الرمز الذي تلقّته Google من نقطة نهاية تسجيل الدخول أو من نقطة نهاية تبادل الرموز المميّزة.
redirect_uri	عند استخدام grant_type=authorization_code، تكون هذه المَعلمة هي عنوان URL المستخدَم في طلب التفويض الأوّلي.
refresh_token	عند grant_type=refresh_token، يتم إرسال الرمز المميّز لإعادة التحميل الذي تلقّته Google من نقطة نهاية تبادل الرموز المميّزة.

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

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

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

عند انتهاء صلاحية رمز الدخول، ترسل 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
   }

ملاحظة: يمكنك اختياريًا عرض refresh_token جديد في ردّك. لمزيد من المعلومات حول وقت إرجاع refresh_token جديد، يُرجى الاطّلاع على استخدام الرموز المميّزة.

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

تحذير: لا تقدِّم للمستخدمين طلبًا مطلوبًا لربط الحساب في بداية المحادثة مع الإجراء الخاص بك. بدلاً من ذلك، يمكنك السماح للمستخدمين الذين لم تتم مصادقتهم بالوصول إلى الاجتماع لإظهار آلية عمل الإجراء الخاص بك، وبعد ذلك لا تطلب منهم ربط الحساب إلا إذا كان ذلك ضروريًا. إذا كان المستخدمون يغادرون "الإجراء" بشكل مستمر بسبب مشاكل في ربط الحساب، لن تروّج Google للإجراء بشكل نشط، ما قد يتسبّب في انخفاض عدد زيارات مستخدمي الإجراء.

ملاحظة: يجب استخدام أداة إنشاء الإجراءات لإنشاء إجراء ينفّذ عملية ربط الحسابات.

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

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

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

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

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

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

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

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

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

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

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