تنفيذ خادم OAuth 2.0

يجب أن يتضمن كل إجراء smart home آلية مصادقة المستخدمين.

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

توضّح هذه الصفحة طريقة إعداد خادم OAuth 2.0 لكي يعمل مع. إجراء smart home.

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

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

على سبيل المثال، إذا كانت نقطة نهاية التفويض متاحة على 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

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

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

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

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

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

الرموز المميزة لإعادة تحميل 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
   }

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

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

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

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

عناوين طلبات نقطة نهاية userinfo
Authorization header	رمز الدخول من النوع "الحامل".

على سبيل المثال، إذا كانت نقطة نهاية 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	اختياري: صورة الملف الشخصي للمستخدم.