ربط الحساب باستخدام بروتوكول 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.
    • دوِّن قيمة Client-ID الصادر عن Google مع الإجراءات الخاصة بك.
    • أدرِج عناوين URL لنقاط نهاية "التفويض" و"تبادل الرموز المميّزة".
  1. انقر على حفظ.

تنفيذ خادم 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 المستخدم إلى نقطة نهاية التفويض من خلال طلب يتضمن المعلَمات التالية:

مَعلمات نقطة نهاية التفويض
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 متعددة، تأكَّد أيضًا من أنّ تم 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 لرموز الدخول

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

مَعلمات نقطة نهاية تبادل الرموز المميّزة
client_id سلسلة تحدِّد مصدر الطلب على أنّه Google. يجب أن تكون هذه السلسلة في نظامك كمعرّف فريد لشركة Google.
client_secret سلسلة سرية سجّلتها لدى Google لخدمتك.
grant_type تمثّل هذه السمة نوع الرمز المميّز الذي يتم تبادله. أيّ منهما authorization_code أو refresh_token
code عندما grant_type=authorization_code، يتم عرض الرمز التي تتلقاها من نقطة نهاية تسجيل الدخول أو نقطة نهاية تبادل الرمز المميز.
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 عملية إعادة التحميل للحصول على رمز دخول جديد من نقطة نهاية تبادل الرموز المميّزة.

الرموز المميزة لإعادة تحميل 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. افتح مشروع "أداة إنشاء الإجراءات" في وحدة تحكّم المهام.
  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" يتضمّن رمز دخول، تحقَّق أولاً من أنّ رمز الدخول صالح (وليس منتهي الصلاحية)، ثم استرِد حساب المستخدم المرتبط من قاعدة البيانات.