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

يتوافق نوع ربط OAuth مع مسارين من بروتوكول OAuth 2.0 المتّبع في المجال، وهما تدفقا الرمز implicit وauthorize.

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

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

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

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

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

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

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

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

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

   

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

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

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

تنفيذ خادم OAuth

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

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

تتضمن جلسة تدفق البريد الضمني OAuth 2.0 التي بدأتها Google المسار التالي:

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

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

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

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

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

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

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

1. تحقّق من القيمتين client_id وredirect_uri لمنع منح إذن الوصول إلى تطبيقات العميل غير المقصودة أو التي تم ضبطها بشكلٍ خاطئ:

   • تأكّد من أنّ client_id يتطابق مع معرِّف العميل الذي خصَّصته لـ Google.
   • تأكَّد من أنّ عنوان URL الذي تحدّده المعلّمة redirect_uri يحتوي على النموذج التالي:

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

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

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

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

4. أرسِل استجابة HTTP التي تعيد توجيه متصفّح المستخدم إلى عنوان URL الذي تحدّده المعلَمة redirect_uri. يمكنك تضمين جميع المعلّمات التالية في جزء عنوان URL:

   • access_token: رمز الدخول الذي أنشأته للتو
   • token_type: السلسلة bearer
   • state: قيمة الحالة غير المعدّلة من الطلب الأصلي في ما يلي مثال على عنوان URL الناتج:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

سيتلقّى معالج إعادة التوجيه "OAuth 2.0" من Google رمز الدخول، وسيؤكّد أنّ قيمة state لم تتغيّر. بعد أن تحصل Google على رمز الدخول لخدمتك، ستُرفِق Google الرمز المميَّز بالمكالمات اللاحقة لاتّخاذ إجراء كجزء من AppRequest.

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

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

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

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

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

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

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

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

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

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

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

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