تنفيذ خادم OAuth 2.0

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يجب أن يتضمّن كل عملية دمج مع Cloud-to-cloud آلية لسماح بالوصول إلى حسابات المستخدمين.

تتيح لك المصادقة ربط حسابات المستخدمين على Google بحسابات المستخدمين في نظام المصادقة. يتيح لك ذلك تحديد المستخدمين عندماتلقّى Fulfillment طلبًا مرتبطًا بالمنزل الذكي. لا يتيح المنزل الذكي من Google استخدام بروتوكول OAuth إلا من خلال مسار رمز التفويض.

توضّح هذه الصفحة كيفية إعداد خادم OAuth 2.0 لكي يعمل مع عملية دمج Cloud-to-cloud.

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

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

• نقطة نهاية التفويض التي تعرِض واجهة مستخدم تسجيل الدخول للمستخدمين الذين لم يسجّلوا الدخول بعد تُنشئ نقطة نهاية التفويض أيضًا رمز تفويض قصير الأمد لتسجيل موافقة المستخدمين على الاستفادة من إذن الوصول المطلوب.

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

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

إرشادات التصميم

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

المتطلبات

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

اقتراحات

ننصحك باتّباع الخطوات التالية:

1. عرض سياسة خصوصية Google: أدرِج رابطًا يؤدي إلى سياسة خصوصية Google على شاشة الموافقة.

2. البيانات التي ستتم مشاركتها: استخدِم لغة واضحة وموجزة لإعلام المستخدم بال data التي تطلبها Google منه والغرض من ذلك.

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

4. إمكانية إلغاء الاشتراك: يجب توفير طريقة للمستخدمين للرجوع أو الإلغاء إذا اختاروا عدم الربط.

5. عملية تسجيل دخول واضحة: تأكَّد من توفُّر طريقة واضحة للمستخدمين لتسجيل الدخول إلى حساباتهم على Google، مثل حقول اسم المستخدم وكلمة المرور أو تسجيل الدخول باستخدام حساب Google.

6. إمكانية إلغاء الربط يجب توفير آلية تتيح للمستخدمين إلغاء ربط الحساب، مثل عنوان URL يؤدي إلى إعدادات حساباتهم على منصتك. بدلاً من ذلك، يمكنك تضمين رابط يؤدي إلى حساب Google حيث يمكن للمستخدمين إدارة حساباتهم المرتبطة.

7. إمكانية تغيير حساب المستخدم: اقترح طريقة للمستخدمين للتبديل بين حساباتهم. ويُعدّ ذلك مفيدًا بشكل خاص إذا كان المستخدمون يميلون إلى استخدام حسابات متعدّدة.

   • إذا كان على المستخدم إغلاق شاشة الموافقة لتبديل الحسابات، أرسِل خطأ قابلاً للاسترداد إلى Google حتى يتمكّن المستخدم من تسجيل الدخول إلى الحساب المطلوب باستخدام ربط OAuth.

8. أدرِج شعارك. عرض شعار شركتك على شاشة الموافقة استخدِم إرشادات الأنماط لوضع شعارك. إذا أردت عرض شعار Google أيضًا، اطّلِع على الشعارات والعلامات التجارية.

مسار رمز التفويض

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

عندما يحتاج أحد تطبيقات Google إلى استدعاء إحدى واجهات برمجة تطبيقات خدمتك، تستخدم 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&user_locale=LOCALE

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

1. تأكَّد من أنّ client_id يتطابق مع معرّف العميل الذي حدّدته لشركة 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
     https://oauth-redirect-sandbox.googleusercontent.com/r/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

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

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

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

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

ضبط كيفية إرسال Google لبيانات الاعتماد إلى خادمك

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

ترسل Google بيانات الاعتماد تلقائيًا في نص الطلب. إذا كان خادم التفويض يتطلّب أن تكون بيانات اعتماد العميل في عنوان الطلب، عليك ضبط عملية دمج Cloud-to-cloud على النحو التالي:

الانتقال إلى Play Console

1. من قائمة المشاريع، انقر على فتح بجانب المشروع الذي تريد العمل عليه.

2. ضمن من السحابة الإلكترونية إلى السحابة الإلكترونية، اختَر تطوير.

3. انقر على فتح بجانب عملية الدمج.

4. انتقِل للأسفل إلى قسم الأذونات (اختيارية) وضَع علامة في مربّع الاختيار إرسال Google لمعرّف العميل والسرية من خلال عنوان المصادقة الأساسية لبروتوكول HTTP.

5. انقر على حفظ لحفظ التغييرات.

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

بعد تسجيل دخول المستخدم وعرض نقطة نهاية التفويض رمز تفويض قصير الأجل على 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. تأكَّد من أنّ رمز التفويض صالح ولم تنته صلاحيته، وأنّ رقم تعريف العميل المحدّد في الطلب يتطابق مع رقم تعريف العميل المرتبط برمز التفويض.
3. تأكَّد من أنّ عنوان URL المحدّد بالمَعلمة redirect_uri مطابق للقيمة المستخدَمة في طلب التفويض الأوّلي.
4. إذا تعذّر عليك التحقّق من جميع المعايير أعلاه، يجب عرض خطأ HTTP 400 Bad Request مع {"error": "invalid_grant"} كنص.
5. بخلاف ذلك، استخدِم رقم تعريف المستخدم من رمز التفويض لإنشاء رمز مميَّز لإعادة التحميل ورمز مميَّز للوصول. يمكن أن تكون هذه الرموز المميّزة أي قيمة سلسلة، ولكن يجب أن تمثل بشكل فريد المستخدم والعميل المخصّص له الرمز المميّز، ويجب أن يكون من الصعب تخمينها. بالنسبة إلى رموز الوصول، سجِّل أيضًا وقت انتهاء صلاحية الرمز، والذي يكون عادةً بعد ساعة من إصدار الرمز. لا تنتهي صلاحية الرموز المميّزة لإعادة التحميل.
6. عرض عنصر 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 لطلبات POST من خلال تنفيذ الخطوات التالية:

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

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

التعامل مع طلبات معلومات المستخدم

نقطة نهاية userinfo هي مورد OAuth 2.0 محمي يعرض مطالبات بشأن المستخدم المرتبط. يُعد تنفيذ نقطة نهاية userinfo واستضافتها اختياريًا، باستثناء حالات الاستخدام التالية:

• تسجيل الدخول إلى حساب مرتبط باستخدام Google One Tap.
• اشتراك سلس على AndroidTV.

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

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

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

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

1. يمكنك استخراج رمز الدخول من عنوان التفويض ومعلومات الإرجاع للمستخدم المرتبط برمز الدخول.
2. إذا كان رمز الدخول غير صالح، يمكنك عرض الخطأ HTTP 401 "غير مصرح به" مع استخدام عنوان الاستجابة WWW-Authenticate. في ما يلي مثال على استجابة خطأ في معلومات المستخدم:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

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

3. إذا كان رمز الدخول صالحًا، يتم عرض الاستجابة HTTP 200 مع كائن JSON التالي في نص HTTPS. الرد:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }
   

   إذا عرضت نقطة نهاية معلومات المستخدم استجابة نجاح HTTP 200، يتم تسجيل الرمز المميز الذي تم استرداده والمطالبات مقابل حساب المستخدم على Google.

   استجابة نقطة نهاية لمعلومات المستخدم
   sub	معرّف فريد يعرّف المستخدِم في نظامك.
   email	عنوان البريد الإلكتروني للمستخدم.
   given_name	اختياري: الاسم الأول للمستخدم.
   family_name	اختياري: اسم العائلة للمستخدم.
   name	اختياري: اسم المستخدم الكامل.
   picture	اختياري: صورة الملف الشخصي للمستخدم.