تنفيذ خادم 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 لرموز الدخول والرموز المميزة لإعادة التحميل
• الرموز المميزة لإعادة تحميل 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 من نقطة نهاية تبادل الرموز المميّزة.

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

بعد أن يسجِّل المستخدم دخوله ويعرِض نقطة نهاية التفويض رمز تفويض قصير الأجل إلى 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. إذا لم تتمكّن من التحقّق من جميع المعايير المذكورة أعلاه، يمكنك عرض رسالة الخطأ "خطأ 400 طلب غير صحيح" في HTTP مع عرض {"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

بالنسبة إلى نقطة نهاية userinfo لمعالجة الطلبات، يُرجى اتِّباع الخطوات التالية:

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

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

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

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",
   }
   

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

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