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

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

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

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

ضبط المشروع

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

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

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

   

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

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

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

تنفيذ خادم OAuth

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

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

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

1. تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. تشير رسالة الأشكال البيانية تسجيل دخول المستخدم إذا لم يكن مسجّلاً الدخول، ويمنح Google إذنًا بالوصول بياناته من خلال واجهة برمجة التطبيقات إذا لم يسبق له منحها الإذن بذلك.
2. تنشئ الخدمة رمز دخول وتعيده إلى Google عن طريق إعادة توجيه متصفّح المستخدم إلى Google باستخدام رمز الدخول المرفق بالطلب.
3. تستدعي Google واجهات برمجة التطبيقات التابعة لخدمتك، وترفق رمز الدخول المميز لكل طلب. تتحقّق خدمتك من أنّ رمز الدخول يمنح 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&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.

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

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

1. افتح مشروع "أداة إنشاء الإجراءات" في وحدة تحكّم المهام.
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. اضبط كيفية سير التدفق إذا وافق المستخدم على ربط حسابه. على سبيل المثال، يمكنك الاتصال بالرد التلقائي على الويب لمعالجة أي منطق مخصص للنشاط التجاري مطلوب والرجوع إلى المشهد الأصلي.
3. انقر على حفظ.

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

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

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

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