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

اقتراحات

ننصحك بإجراء ما يلي:

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

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

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

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

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

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

6. أدرِج شعارك. عرض شعار شركتك على شاشة طلب الموافقة استخدِم إرشادات النمط لوضع شعارك. إذا أردت أيضًا عرض شعار 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	اختياري: صورة الملف الشخصي للمستخدم.