بروتوكول OAuth 2.0 للتطبيقات المتوافقة مع الكمبيوتر المكتبي

يشرح هذا المستند كيفية استخدام تطبيقات الكمبيوتر المكتبي (مثل التطبيقات التي تعمل على أنظمة التشغيل Windows أو macOS أو Linux أو أدوات واجهة سطر الأوامر (CLI)) لنقاط نهاية OAuth 2.0 من Google من أجل السماح بالوصول إلى Google APIs.

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

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

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

المكتبات والعيّنات

ننصحك باستخدام مكتبات عملاء Google API للغة البرمجة التي تستخدمها (مثل Python وJava وNode.js وGo و‎.NET) عند تنفيذ OAuth 2.0 لتطبيقات الكمبيوتر المكتبي. تتولّى مكتبات العملاء إدارة تفويض المستخدمين والرموز المميّزة، ما يجعل عملية التنفيذ أبسط وأقل عرضة للأخطاء مقارنةً باستخدام نقاط نهاية HTTP/REST ذات المستوى الأدنى مباشرةً.

بالنسبة إلى التطبيقات المتوافقة مع الأجهزة الجوّالة، يُرجى الاطّلاع على دليلَي التفويض لنظامَي التشغيل Android وiOS.

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

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

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

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

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

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

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

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

1. انتقِل إلى صفحة "العملاء".
2. انقر على إنشاء عميل.
3. اختَر نوع التطبيق تطبيق متوافق مع الكمبيوتر المكتبي.
4. في حقل الاسم، أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم في صفحة "العملاء" الخاصة بمشروعك لتحديد العميل.
5. انقر على إنشاء.

يتم إنشاء معرِّف العميل وسر العميل وعرضهما في وحدة تحكّم Google Cloud. التطبيقات المتوافقة مع الكمبيوتر المكتبي هي برامج عملاء عامة ولا يمكنها الحفاظ على سرية المعلومات السرية. استخدِم دائمًا مفتاح الحماية لتبادل الرموز (PKCE) عند طلب رموز التفويض.

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

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

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

يحتوي مستند نطاقات OAuth 2.0 API على قائمة كاملة بالنطاقات التي يمكنك استخدامها للوصول إلى Google APIs.

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

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

الخطوة 1: إنشاء أداة التحقّق من الرمز والتحدي

تتيح Google استخدام بروتوكول Proof Key for Code Exchange (PKCE) لجعل مسار التطبيق المثبّت أكثر أمانًا. يتم إنشاء أداة تحقّق فريدة من الرمز لكل طلب تفويض، ويتم إرسال قيمتها المحوَّلة، والتي تُعرف باسم "code_challenge"، إلى خادم التفويض للحصول على رمز التفويض.

إنشاء أداة التحقّق من الرمز

‫code_verifier هي سلسلة عشوائية مشفّرة ذات عشوائية عالية تستخدم الأحرف غير المحجوزة [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"، بحد أدنى للطول يبلغ 43 حرفًا وحد أقصى للطول يبلغ 128 حرفًا.

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

إنشاء رمز التحقّق

تتوفّر طريقتان لإنشاء تحدّي الرمز.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

الخطوة 2: إرسال طلب إلى خادم OAuth 2.0 من Google

للحصول على تفويض المستخدم، أرسِل طلبًا إلى خادم التفويض في Google على https://accounts.google.com/o/oauth2/v2/auth. تعالج نقطة النهاية هذه عملية البحث عن الجلسات النشطة، وتصادق المستخدم، وتحصل على موافقته. لا يمكن الوصول إلى نقطة النهاية إلا عبر طبقة المقابس الآمنة (SSL)، وهي ترفض اتصالات HTTP (غير المتوافقة مع طبقة المقابس الآمنة).

يتيح خادم التفويض مَعلمات سلسلة طلب البحث التالية للتطبيقات المثبّتة:

نماذج عناوين URL للتفويض

تعرض علامات التبويب أدناه نماذج عناوين URL للمصادقة لخيارات عناوين URI المختلفة لإعادة التوجيه.

عنوانا URL متطابقان باستثناء قيمة المَعلمة redirect_uri. وتتضمّن عناوين URL أيضًا المَعلمتَين المطلوبتَين response_type وclient_id، بالإضافة إلى المَعلمة الاختيارية state. يحتوي كل عنوان URL على فواصل أسطر ومسافات لتسهيل القراءة.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

الخطوة 3: تطلب Google من المستخدم الموافقة

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

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

الخطوة 4: معالجة استجابة خادم OAuth 2.0

تعتمد الطريقة التي يتلقّى بها تطبيقك ردّ التفويض على مخطّط URI لإعادة التوجيه الذي يستخدمه. بغض النظر عن المخطط، سيحتوي الردّ إما على رمز تفويض (code) أو خطأ (error). على سبيل المثال، يشير error=access_denied إلى أنّ المستخدم رفض الطلب.

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

الخطوة 5: تبديل رمز التفويض برموز مميّزة لإعادة التحميل والوصول

لتبديل رمز التفويض برمز دخول، يمكنك استدعاء نقطة النهاية https://oauth2.googleapis.com/token وضبط المَعلمات التالية:

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

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

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

إنشاء إثبات DPoP

توضّح الخطوات التالية كيفية إنشاء إثبات DPoP باستخدام OpenSSL من سطر الأوامر:

1. إنشاء مفتاحَي تشفير EC P-256:

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. إنشاء عنوان DPoP:

   يجب أن يتضمّن العنوان المطالبات typ وalg وjwk (المفتاح العام). تمثّل القيمتان x وy الإحداثيات المشفّرة باستخدام Base64Url لمفتاح EC العام. ترميز Base64Url لملف JSON هذا:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. إنشاء حمولة DPoP:

   يجب أن تتضمّن الحمولة jti (معرّف فريد للطلب) وhtm (طريقة HTTP، مثل POST) وhtu (معرّف الموارد المنتظم (URI) لبروتوكول HTTP، مثل https://oauth2.googleapis.com/token) وiat (وقت الإصدار). إذا تلقّيت رقمًا خاصًا من الخادم في رأس DPoP-Nonce في الردّ على طلب سابق، يجب تضمين قيمة هذا الرقم في مطالبة nonce. تكون مطالبة nonce اختيارية لعمليات تبادل رموز التفويض، ولا تُستخدم إلا عند تلقّي عنوان DPoP-Nonce سابقًا. ترميز Base64Url لملف JSON هذا:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   تعتمد قيمة jti على نوع التبادل:

   • بالنسبة إلى عمليات تبادل رموز التفويض، يجب أن تكون قيمة jti هي تجزئة SHA256 لرمز التفويض بترميز Base64Url: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
   • بالنسبة إلى عمليات تبادل الرموز المميزة لإعادة التحميل، يجب أن تكون قيمة jti معرّفًا فريدًا لكل طلب: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
4. التوقيع على الإثبات:

   ادمج العنوان المرمّز والحمولة مع نقطة (.)، ثم وقِّع النتيجة باستخدام مفتاحك الخاص باستخدام ES256. يُرجى العِلم أنّ JWS يتطلّب أن يكون التوقيع بتنسيق R | S أولي مدمج (64 بايت لـ P-256). في حال استخدام OpenSSL مباشرةً، يجب تحويل التوقيع التلقائي المرمَّز بتنسيق ASN.1 DER إلى هذا التنسيق الأولي.

تتم الإشارة إلى عملية التبادل الناجحة من خلال استجابة 200 OK تحتوي على الرموز المميّزة. إذا تم استخدام إثبات DPoP صالح أثناء عملية التبادل، سيكون الرمز المميز لإعادة التحميل الذي تعرضه Google مرتبطًا بمفتاحك من خلال DPoP، ولكن لن تكون رموز الدخول مرتبطة من خلال DPoP. ستحتفظ رموز الدخول بـ token_type Bearer بدلاً من DPoP. بالإضافة إلى ذلك، يعرض Google عنوان HTTP يتضمّن DPoP-Nonce في الاستجابة. يجب أن يخزّن برنامجك هذا الرقم الخاص مؤقتًا ويضمّنه في مطالبة nonce لإثبات DPoP في الطلبات اللاحقة (مثل عند استبدال الرمز المميز لإعادة التحميل برمز دخول جديد، أو عند طلب واجهات برمجة تطبيقات محمية ببروتوكول DPoP). باستخدام هذا الرقم الخاص الصادر مبكرًا، يمكنك تجنُّب حدوث خطأ إضافي في الذهاب والعودة (use_dpop_nonce) في طلبك التالي.

يجب تضمين إثباتات DPoP في طلبات تبادل الرموز المميزة التي يتم إجراؤها باستخدام الرموز المميزة لإعادة التحميل المرتبطة بـ DPoP.

يحدث فشل في عملية التبادل إذا كان عنوان DPoP غير متوفّر عندما يكون متوقّعًا أو غير صالح، أو إذا كان الإثبات يستخدم مفتاحًا مختلفًا عن المفتاح المرتبط بالرمز المميّز. وفي هذه الحالات، يعرض الخادم الخطأ 400 Bad Request. إذا كان إثبات DPoP يتضمّن مطالبات htm أو htu غير متطابقة، أو iat منتهي الصلاحية، أو jti مُعاد استخدامه، أو توقيع غير صالح، ستعرض Google رمز الخطأ invalid_dpop_proof. إذا كان رمز nonce لبروتوكول DPoP مطلوبًا، مثلاً أثناء تبادل الرمز المميز لإعادة التحميل، وكان إثبات DPoP لا يتضمّن مطالبة nonce، أو كانت قيمة nonce غير مقبولة للخادم (على سبيل المثال، انتهت صلاحيتها أو تم استخدامها من قبل أو غير صحيحة)، تعرض Google رمز الخطأ use_dpop_nonce مع عنوان HTTP DPoP-Nonce يحتوي على رمز nonce جديد يمكنك استخدامه في طلب لاحق. قد تؤدي حالات الفشل الأخرى إلى عرض invalid_grant.

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

يحتوي الردّ على الحقول التالية:

يعرض المقتطف التالي نموذجًا لعناوين الاستجابة والنص الأساسي الناجحَين عند استخدام DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

الخطوة 6: التحقّق من النطاقات التي منحها المستخدمون

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

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

لمزيد من المعلومات التفصيلية، يُرجى الاطّلاع على كيفية التعامل مع الأذونات الدقيقة.

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

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

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

استدعاء 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) يتضمّن المَعلمات التالية في نص الطلب:

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

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

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

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

لاستخدام DPoP مع رمز مميّز لإعادة التحميل، يجب إنشاء رمز JWT جديد وفريد لإثبات DPoP للطلب. راجِع إنشاء إثبات DPoP للحصول على تعليمات مفصّلة حول إنشاء مفتاحَي التشفير وإنشاء رمز JWT.

تتم الإشارة إلى عملية التبادل الناجحة من خلال استجابة 200 OK تحتوي على رمز دخول جديد. عند استخدام DPoP، يكون token_type هو Bearer. ويؤكّد الردّ الناجح قبول إثبات DPoP للرمز المميّز لإعادة التحميل. قد تعرض Google أيضًا عنوان HTTP جديدًا باسم DPoP-Nonce في الاستجابة. وفي حال عرضه، يجب أن يخزّن العميل هذا الرقم الخاص مؤقتًا ويضمّنه في مطالبة nonce لإثبات DPoP في الطلبات اللاحقة.

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

يعرض المقتطف التالي نموذجًا لعناوين الاستجابة والنص الأساسي الناجحَين عند استخدام DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "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 مع رمز خطأ.

طُرق إعادة التوجيه إلى التطبيق

حماية تطبيقاتك

الوصول المستند إلى الوقت

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

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

محتوى إضافي للقراءة

يحدّد معيار "أفضل الممارسات الحالية" (BCP) الصادر عن "فريق مهام هندسة الإنترنت" (IETF) بشأن OAuth 2.0 للتطبيقات الأصلية العديد من أفضل الممارسات الموضّحة هنا.