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

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

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

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

البدائل

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

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

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

يجب أن يفعّل أي تطبيق يطلب بيانات من Google APIs واجهات برمجة التطبيقات هذه في "وحدة تحكّم واجهة برمجة التطبيقات".

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

  1. افتح مكتبة واجهات برمجة التطبيقات في Google API Console.
  2. اختَر مشروعًا أو أنشِئ مشروعًا جديدًا إذا طُلب منك ذلك.
  3. تعرض "مكتبة واجهة برمجة التطبيقات" جميع واجهات برمجة التطبيقات المتاحة، مجمّعة حسب مجموعة المنتجات ومدى رواجها. إذا لم تظهر واجهة برمجة التطبيقات التي تريد تفعيلها في القائمة، استخدِم البحث للعثور عليها، أو انقر على عرض الكل في مجموعة المنتجات التي تنتمي إليها.
  4. اختَر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على الزر تفعيل.
  5. فعِّل الفوترة إذا طُلب منك ذلك.
  6. اقرأ بنود خدمة واجهة برمجة التطبيقات ووافِق عليها إذا طُلب منك ذلك.

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

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

  1. انتقِل إلى صفحة "العملاء".
  2. انقر على إنشاء عميل (Create Client).
  3. اختَر نوع التطبيق أجهزة التلفزيون والأجهزة ذات الإدخال المحدود.
  4. أدخِل اسمًا لعميل OAuth 2.0 وانقر على إنشاء.

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

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

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

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

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

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

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

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

يسجّل المستخدم الدخول على جهاز منفصل يحتوي على متصفّح

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

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

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

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

معرّف العميل لتطبيقك يمكنك العثور على هذه القيمة في صفحة "العملاء" ضمن Cloud Console.
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.

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

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

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

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

المعلمات
client_id معرّف العميل لتطبيقك يمكنك العثور على هذه القيمة في صفحة "العملاء" ضمن Cloud Console.
client_secret سر العميل لـ client_id المقدَّم. يمكنك العثور على هذه القيمة في صفحة "العملاء" ضمن Cloud Console.
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"
}

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

إذا أرسل الجهاز طلبات استطلاع بشكل متكرر جدًا، يعرض الخادم رمز حالة استجابة HTTP 403 (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

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

يمكنك تجربة جميع واجهات Google APIs والاطّلاع على نطاقاتها في مساحة بروتوكول 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) يتضمّن المَعلمات التالية في نص الطلب:

الاسم القيمة
client_id معرِّف العميل الذي تم الحصول عليه من وحدة تحكّم واجهة برمجة التطبيقات
client_secret اختياريّ

سر العميل الذي تم الحصول عليه من وحدة تحكّم واجهة برمجة التطبيقات

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&
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 https://www.googleapis.com/auth/calendar.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 API

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

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

تنفيذ ميزة "الحماية العابرة للحساب"

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

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