تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تنفيذ خادم OAuth 2.0

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

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

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

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

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

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

تبدأ جلسة تدفق رمز تفويض OAuth 2.0 التي بدأتها Google بالمسار التالي:

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

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

تأكّد من أنّ client_id يتطابق مع معرّف العميل الذي حدّدته لشركة Google، وأنّ redirect_uri يطابق عنوان URL لإعادة التوجيه المقدّم من Google لخدمتك. تُعد عمليات التحقّق هذه مهمة لمنع منح الوصول إلى تطبيقات العملاء غير المقصودة أو التي تم ضبطها بشكلٍ خاطئ. إذا كنت توفّر مسارات متعدّدة لبروتوكول OAuth 2.0، تأكّد أيضًا من أنّ response_type هو code.
تحقق مما إذا كان المستخدم قد سجّل الدخول إلى الخدمة. إذا لم يكن المستخدم مسجّلاً الدخول، أكمِل خطوات تسجيل الدخول إلى الخدمة أو الاشتراك.
يمكنك إنشاء رمز تفويض لتستخدمه Google للوصول إلى واجهة برمجة التطبيقات. يمكن أن يكون رمز التفويض أي قيمة سلسلة، ولكن يجب أن يمثل المستخدم بشكل فريد، والعميل المُخصّص للرمز المميَّز، ووقت انتهاء صلاحية الرمز، ولا يمكن تخمينه. عادةً ما تصدر رموز التفويض التي تنتهي صلاحيتها بعد 10 دقائق تقريبًا.

تأكّد من أن عنوان URL المحدّد في المعلَمة redirect_uri يحتوي على النموذج التالي:

  https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

أعِد توجيه متصفّح المستخدم إلى عنوان 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 من خلال تنفيذ الخطوات التالية:

تحقّق من أنّ client_id يحدّد مصدر الطلب على أنّه أصل مصرّح به، وأنّ client_secret يطابق القيمة المتوقّعة.
تحقق من أن رمز التفويض صالح ولم تنته صلاحيته، وأن معرّف العميل المحدد في الطلب يتطابق مع رقم تعريف العميل المرتبط برمز التفويض.
تأكّد من أن عنوان URL المحدّد في المعلَمة redirect_uri مطابق للقيمة المستخدَمة في طلب التفويض المبدئي.
إذا لم تتمكّن من التحقّق من جميع المعايير المذكورة أعلاه، يمكنك عرض رسالة الخطأ "خطأ 400 طلب غير صحيح" في HTTP مع عرض {"error": "invalid_grant"} على أنّه النص الأساسي.
وبخلاف ذلك، يمكنك استخدام رقم تعريف المستخدم من رمز التفويض لإنشاء رمز مميز لإعادة التحميل ورمز دخول. يمكن أن تكون هذه الرموز المميّزة أي قيمة للسلسلة، ولكن يجب أن تمثّل بشكل فريد المستخدم والعميل الذي يمثّل الرمز المميّز له، ويجب ألّا يكون هناك تخمين. بالنسبة إلى رموز الدخول، سجِّل أيضًا وقت انتهاء صلاحية الرمز المميز، الذي يكون عادةً بعد ساعة من إصدار الرمز المميز. لا تنتهي صلاحية الرموز المميزة لإعادة التحميل.

عرض كائن 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 عن طريق تنفيذ الخطوات التالية:

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

عرض كائن 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 لمعالجة الطلبات، يُرجى اتِّباع الخطوات التالية:

يمكنك استخراج رمز الدخول من رأس التفويض ومعلومات العرض للمستخدم المرتبط برمز الدخول.
إذا كان رمز الدخول غير صالح، اعرض خطأ HTTP 401 غير مُصرَّح به باستخدام عنوان الاستجابة WWW-Authenticate. في ما يلي مثال على استجابة خطأ userinfo:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
في حال عرض أي خطأ آخر غير صحيح، أو ظهور أي خطأ آخر غير صحيح أثناء عملية الربط، لن يكون الخطأ قابلاً للإصلاح، وسيتم تجاهل الرمز المميز الذي تم استرداده وسيكون على المستخدم بدء عملية الربط مرة أخرى.

إذا كان الرمز المميّز للوصول صالحًا، يمكنك عرض الاستجابة 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`	اختياري: صورة الملف الشخصي للمستخدم

قائمة التحقّق من مطوّري البرامج

إنشاء مشروع "مهام"