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

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

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

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

البدائل

في حال كتابة تطبيق لنظام أساسي، مثل Android أو iOS أو macOS أو Linux أو Windows (بما في ذلك Universal Windows Platform)، التي يمكنها الوصول إلى المتصفح والإدخال الكامل فقط، استخدم تدفق 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 التالي المَعلمات:

المعلمات
client_id مطلوب

معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في API Console Credentials page

scope مطلوب

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

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

أمثلة

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

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

يتيح هذا الرمز للجهاز الذي يشغِّل التطبيق أن يحدّد بأمان ما إذا كان المستخدم قد منح أو رفض وصوله.

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

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

{
  "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.

صمِّم واجهة المستخدم (UI) مع وضع القواعد التالية في الاعتبار:

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

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

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

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

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

المعلمات
client_id معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في API Console Credentials page
client_secret سر العميل لملف client_id المقدَّم. يمكنك العثور على هذه القيمة في API Console Credentials page
device_code إنّ device_code الذي يعرضه خادم التفويض في الخطوة 2.
grant_type اضبط هذه القيمة على urn:ietf:params:oauth:grant-type:device_code.

أمثلة

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

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 APIs نيابةً عن المستخدم. (scope في الاستجابة أي واجهات برمجة تطبيقات جهازك الوصول إليها).

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

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

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

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

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

تم رفض الوصول

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

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

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

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

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

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

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

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

أخطاء أخرى

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

خطأ رمز حالة HTTP الوصف
admin_policy_enforced 400 يتعذّر على حساب Google تفويض نطاق واحد أو أكثر من النطاقات المطلوبة بسبب سياسات مشرف Google Workspace. الاطّلاع على مساعدة مشرف Google Workspace مقالة التحكم في تحديد الجهات الخارجية وصول التطبيقات الداخلية إلى بيانات Google Workspace لمزيد من المعلومات حول كيفية قد يقيّد المشرف إمكانية الوصول إلى النطاقات إلى أن يتم منح إذن الوصول صراحةً إلى بروتوكول OAuth. معرِّف العميل.
invalid_client 401

لم يتم العثور على عميل OAuth. على سبيل المثال، يحدث هذا الخطأ إذا كانت قيمة المعلمة client_id غير صالحة.

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

invalid_grant 400 قيمة المعلَمة code غير صالحة أو تمت المطالبة بها من قبل أو لا يمكن تحليله.
unsupported_grant_type 400 قيمة المعلمة grant_type غير صالحة.
org_internal 403 معرِّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من إمكانية الوصول إلى حسابات Google. في جلسة محددة مؤسسة Google Cloud: أكِّد نوع المستخدم لضبط تطبيق OAuth.

الاتصال بـ Google APIs

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

يمكنك تجربة جميع واجهات Google APIs وعرض نطاقاتها من خلال ملعب OAuth 2.0.

أمثلة على الحصول على HTTP

اتصال drive.files نقطة النهاية (واجهة برمجة تطبيقات ملفات Drive) باستخدام Authorization: Bearer HTTP على النحو التالي. ملاحظة: يجب تحديد رمز الدخول الخاص بك:

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) بأنه يتضمن المعلَمات التالية:

الحقول
client_id معرّف العميل الذي تم الحصول عليه من API Console.
client_secret سر العميل الذي تم الحصول عليه من API Console.
grant_type بالنسبة المحددة في مواصفات OAuth 2.0، يجب ضبط قيمة هذا الحقل على refresh_token.
refresh_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 للأجهزة إلا مع النطاقات التالية:

OpenID Connect، تسجيل الدخول باستخدام حساب Google

  • email
  • openid
  • profile

واجهة برمجة تطبيقات Drive

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly

تطبيق ميزة "الحماية العابرة للحساب"

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

في ما يلي بعض الأمثلة على أنواع الأحداث التي ترسلها "خدمة الحماية العابرة للحساب" من Google إلى تطبيقك:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

يمكنك الاطّلاع على حماية حسابات المستخدمين باستخدام صفحة "الحماية العابرة للحساب" للحصول على مزيد من المعلومات حول كيفية تفعيل ميزة "الحماية العابرة للحساب" والاطّلاع على قائمة كاملة بالأحداث المتاحة.