OAuth 2.0 لتطبيقات التلفزيون والأجهزة ذات الإدخال المحدود

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

يتيح بروتوكول OAuth 2.0 للمستخدمين مشاركة بيانات محدَّدة مع أحد التطبيقات والحفاظ على خصوصية أسماء المستخدمين وكلمات المرور والمعلومات الأخرى. على سبيل المثال، يمكن لتطبيق تلفزيوني استخدام OAuth 2.0 للحصول على إذن لتحديد ملف مخزّن على Google Drive.

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

البدائل

إذا كنت تنشئ تطبيقًا لنظام أساسي، مثل Android أو iOS أو macOS أو Linux أو Windows (بما في ذلك نظام التشغيل Universal Windows الأساسي)، الذي يمكنه الوصول إلى المتصفّح وإمكانيات الإدخال الكاملة، يمكنك استخدام مسار OAuth 2.0 لتطبيقات الأجهزة الجوّالة وأجهزة سطح المكتب. (يجب استخدام هذه العملية حتى إذا كان تطبيقك أداة سطر أوامر بدون واجهة رسومية).

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

المتطلبات الأساسية

تفعيل واجهات برمجة التطبيقات لمشروعك

يجب أن يفعّل أي تطبيق يستدعي Google APIs واجهات برمجة التطبيقات هذه في API Console.

لتفعيل واجهة برمجة تطبيقات لمشروعك، اتّبِع الخطوات التالية:

1. Open the API Library في Google API Console.
2. If prompted, select a project, or create a new one.
3. تعرض API Library جميع واجهات برمجة التطبيقات المتاحة، مجمّعة حسب مجموعة المنتجات ورواجها. إذا لم تكن واجهة برمجة التطبيقات التي تريد تفعيلها مرئية في القائمة، استخدِم ميزة البحث للعثور عليها أو انقر على عرض الكل في مجموعة المنتجات التي تنتمي إليها.
4. اختَر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على الزر تفعيل.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

إنشاء بيانات اعتماد التفويض

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

1. Go to the Credentials page.
2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
3. اختَر نوع التطبيق أجهزة التلفزيون والأجهزة التي تتطلّب إدخال بيانات محدودة.
4. أدخِل اسمًا لعميل OAuth 2.0 وانقر على إنشاء.

تحديد نطاقات الوصول

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

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

اطّلِع على قائمة النطاقات المسموح بها للتطبيقات أو الأجهزة المثبَّتة.

الحصول على رموز دخول OAuth 2.0

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

1. يرسل تطبيقك طلبًا إلى خادم تفويض Google الذي يحدِّد النطاقات التي سيطلب تطبيقك إذنًا للوصول إليها.
2. ويستجيب الخادم بعدة معلومات يتم استخدامها في الخطوات اللاحقة، مثل رمز الجهاز ورمز المستخدم.
3. يمكنك عرض معلومات يمكن للمستخدم إدخالها على جهاز منفصل لتفويض تطبيقك.
4. يبدأ تطبيقك في الاستعلام عن خادم التفويض في Google لتحديد ما إذا كان المستخدم قد أذن لتطبيقك.
5. ينتقل المستخدم إلى جهاز يتضمّن إمكانات إدخال أكثر ثراءً، ويشغِّل متصفّح ويب، وينتقل إلى عنوان URL المعروض في الخطوة 3 ويُدخِل رمزًا يظهر أيضًا في الخطوة 3. ويمكن للمستخدم منح (أو رفض) إذن الوصول إلى تطبيقك.
6. يتضمن الرد التالي على طلب الاستطلاع الرموز المميزة التي يحتاجها تطبيقك للموافقة على الطلبات نيابةً عن المستخدم. (إذا رفض المستخدم الوصول إلى تطبيقك، لن يحتوي الردّ على الرموز المميّزة.)

توضِّح الصورة أدناه هذه العملية:

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

الخطوة 1: طلب رموز الجهاز والمستخدم

في هذه الخطوة، يُرسِل جهازك طلب HTTP POST إلى خادم التفويض في Google على العنوان https://oauth2.googleapis.com/device/code، والذي يحدِّد هوية تطبيقك بالإضافة إلى نطاقات الوصول التي يريد تطبيقك الوصول إليها نيابةً عن المستخدم. يجب استرداد عنوان URL هذا من مستند الاكتشاف باستخدام قيمة البيانات الوصفية device_authorization_endpoint. يجب تضمين مَعلمات طلب HTTP التالية:

أمثلة

يعرض المقتطف التالي نموذج طلب:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

يعرض هذا المثال أمر curl لإرسال الطلب نفسه:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

الخطوة 2: التعامل مع استجابة خادم التفويض

سيعرِض خادم التفويض أحد الردود التالية:

استجابة النجاح

إذا كان الطلب صالحًا، ستكون استجابتك كائن JSON يحتوي على السمات التالية:

يعرض المقتطف التالي نموذجًا للاستجابة:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

استجابة تجاوز الحصة

إذا تجاوزت طلبات رموز الأجهزة الحصة المرتبطة برقم تعريف العميل، ستتلقّى استجابة 403 تتضمّن الخطأ التالي:

{
  "error_code": "rate_limit_exceeded"
}

في هذه الحالة، استخدِم استراتيجية التراجع لتقليل معدّل الطلبات.

الخطوة 3: عرض رمز المستخدم

عرض verification_url وuser_code الحاصلَين في الخطوة 2 على المستخدم يمكن أن تحتوي كلتا القيمتَين على أي حرف قابل للطباعة من مجموعة أحرف US-ASCII. يجب أن يوجّه المحتوى الذي تعرِضه للمستخدم إلى الانتقال إلى verification_url على جهاز منفصل وإدخال user_code.

يجب تصميم واجهة المستخدم مع مراعاة القواعد التالية:

• user_code
  • يجب عرض السمة user_code في حقل يمكنه التعامل مع 15 حرفًا بحجم "عرض" (W). بعبارة أخرى، إذا كان بإمكانك عرض الرمز WWWWWWWWWWWWWWW بشكل صحيح، يعني ذلك أنّ واجهة المستخدم صالحة، وننصحك باستخدام قيمة السلسلة هذه عند اختبار طريقة عرض الرمز user_code في واجهة المستخدم.
  • الرمز user_code حسّاس لحالة الأحرف ويجب عدم تعديله بأي شكل من الأشكال، مثل تغيير حالة الأحرف أو إدراج أحرف تنسيق أخرى.
• verification_url
  • يجب أن تكون المساحة التي تعرض فيها verification_url عريضة بما يكفي لمعالجة verification_url
  • يجب عدم تعديل verification_url بأي شكل من الأشكال، إلا لإزالة المخطّط للعرض بشكل اختياري. إذا كنت تخطّط لإزالة المخطّط (مثل https://) من عنوان URL لأسباب متعلقة بالعرض، تأكّد من أنّ تطبيقك يمكنه التعامل مع الصيغتَين http وhttps.

الخطوة 4: الاستعلام عن خادم التفويض في Google

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

يجب أن يواصل الجهاز المُرسِل إرسال طلبات الاستطلاع إلى أن يتلقّى استجابة تشير إلى أنّ المستخدم قد ردّ على طلب الوصول أو إلى أن تنتهي صلاحية device_code وuser_code اللذَين تم الحصول عليهما في الخطوة 2. يحدِّد العنصر interval الذي تم إرجاعه في الخطوة 2 مقدار الوقت بالثواني الذي يجب الانتظاره بين الطلبات.

عنوان URL لنقطة نهاية الاستطلاع هو https://oauth2.googleapis.com/token. يحتوي طلب الاستطلاع على المَعلمات التالية:

أمثلة

يعرض المقتطف التالي نموذج طلب:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

يعرض هذا المثال أمر curl لإرسال الطلب نفسه:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

الخطوة 5: ردّ المستخدم على طلب الوصول

تعرض الصورة التالية صفحة مشابهة لما يظهر للمستخدمين عند الانتقال إلى verification_url الذي عرضته في الخطوة 3:

بعد إدخال user_code وتسجيل الدخول إلى Google في حال لم يسبق لك تسجيل الدخول، ستظهر للمستخدم شاشة موافقة مثل الشاشة الموضّحة أدناه:

الخطوة 6: التعامل مع الردود على طلبات الاستطلاعات

يستجيب خادم التفويض في Google لكل طلب فحص بأحد الردّين التاليين:

تم منحك إمكانية الوصول

إذا منح المستخدم الإذن بالوصول إلى الجهاز (عن طريق النقر على Allow على شاشة الموافقة)، سيتضمّن الردّ رمزَي دخول وإعادة تحميل. تتيح الرموز المميّزة لجهازك الوصول إلى واجهات برمجة تطبيقات Google نيابةً عن المستخدم. (تحدّد السمة scope في الاستجابة واجهات برمجة التطبيقات التي يمكن للجهاز الوصول إليها).

في هذه الحالة، يحتوي ردّ واجهة برمجة التطبيقات على الحقول التالية:

يعرض المقتطف التالي نموذجًا للرد:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

تم رفض الوصول

إذا رفض المستخدم منح إذن الوصول إلى الجهاز، ستكون استجابة الخادم 403 لرمز حالة استجابة HTTP (Forbidden)، وهي تتضمّن الخطأ التالي:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

التفويض في انتظار المراجعة

إذا لم يُكمِل المستخدم عملية التفويض بعد، يعرض الخادم رمز حالة استجابة HTTP هو 428 (Precondition Required). يحتوي الردّ على الخطأ التالي:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

إجراء الاستطلاعات بشكل متكرر جدًا

إذا كان الجهاز يرسل طلبات الاستطلاع بشكل متكرر جدًا، سيعرض الخادم رمز حالة استجابة HTTP 403 (Forbidden)، حيث تحتوي الاستجابة على الخطأ التالي:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

أخطاء أخرى

يعرض خادم التفويض أيضًا أخطاء إذا كان طلب الاستطلاع لا يتضمّن أيًا من المَعلمات المطلوبة أو إذا كانت قيمة المَعلمة غير صحيحة. تتضمّن هذه الطلبات عادةً رمز استجابة HTTP 400 (Bad Request) أو 401 (Unauthorized). وتتضمن هذه الأخطاء ما يلي:

استدعاء واجهات برمجة تطبيقات Google

بعد أن يحصل تطبيقك على رمز مميّز للوصول، يمكنك استخدام الرمز المميّز لإجراء طلبات إلى واجهة برمجة تطبيقات Google نيابةً عن حساب مستخدم معيّن إذا تم منح نطاق الوصول المطلوب من واجهة برمجة التطبيقات. لإجراء ذلك، يمكنك تضمين رمز الدخول في طلب إلى واجهة برمجة التطبيقات عن طريق تضمين معلَمة طلب البحث access_token أو قيمة Bearer لعنوان HTTP يتضمّن Authorization. يُفضّل استخدام عنوان HTTP كلما أمكن، لأنّ سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. في معظم الحالات، يمكنك استخدام مكتبة عملاء لإعداد طلباتك إلى واجهات برمجة تطبيقات Google (على سبيل المثال، عند طلب Drive Files API).

يمكنك تجربة جميع واجهات برمجة تطبيقات Google والاطّلاع على نطاقات الوصول إليها على مساحة بروتوكول OAuth 2.0.

أمثلة على طلبات HTTP GET

قد يبدو طلب البيانات من نقطة نهاية drive.files (Drive Files API) باستخدام عنوان HTTP Authorization: Bearer على النحو التالي. يُرجى العِلم أنّك بحاجة إلى تحديد رمز الدخول الخاص بك:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

في ما يلي طلب بيانات من واجهة برمجة التطبيقات نفسها للمستخدم الذي تمّت مصادقة بياناته باستخدام مَعلمة سلسلة طلب البحث access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

أمثلة على curl

يمكنك اختبار هذه الأوامر باستخدام تطبيق سطر الأوامر curl. في ما يلي مثال يستخدم خيار عنوان HTTP (الخيار المفضّل):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

أو يمكنك بدلاً من ذلك استخدام خيار مَعلمة سلسلة الطلب:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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

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

لإعادة تحميل رمز مميّز للوصول، يُرسِل تطبيقك طلبًا عبر HTTPS POST إلى خادم التفويض في Google‏ (https://oauth2.googleapis.com/token) الذي يتضمّن المَعلمات التالية:

يعرض المقتطف التالي نموذج طلب:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

ما دام المستخدم لم يُبطل الإذن الذي منحه للتطبيق، يعرض خادم الرموز المميّزة عنصر JSON يحتوي على رمز مميّز جديد للوصول. يعرض المقتطف التالي نموذجًا للاستجابة:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

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

إبطال رمز مميّز

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

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

لإبطال رمز مميّز آليًا، يُرسِل تطبيقك طلبًا إلى https://oauth2.googleapis.com/revoke ويُدرِج الرمز المميّز كمَعلمة:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

يمكن أن يكون الرمز المميز رمز دخول أو رمزًا مميزًا لإعادة التحميل. إذا كان الرمز المميّز هو رمز دخول وكان لديه رمز مميّز مقابل لإعادة التحميل، سيتم أيضًا إلغاء رمز إعادة التحميل.

إذا تمت معالجة الإبطال بنجاح، يكون رمز حالة HTTP للاستجابة هو 200. في حالات الخطأ، يتم عرض رمز حالة HTTP 400 مع رمز خطأ.

النطاقات المسموح بها

لا تتوفّر عملية OAuth 2.0 للأجهزة إلا بالنطاقات التالية: