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

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

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

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

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

البدائل

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

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

المكتبات والنماذج

ننصحك باستخدام المكتبات والنماذج التالية لمساعدتك في تنفيذ مسار OAuth 2.0 الموضّح في هذا المستند:

• مكتبة AppAuth لنظام Android
• مكتبة AppAuth لنظام التشغيل iOS
• OAuth للتطبيقات: نماذج Windows

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

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

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

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

1. Open the API Library في Google API Console.
2. If prompted, select a project, or create a new one.
3. استخدِم صفحة "المكتبة" للعثور على YouTube Data API وتفعيلها. ابحث عن أي واجهات برمجة تطبيقات أخرى سيستخدمها تطبيقك وفعّلها أيضًا.

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

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

1. Go to the Credentials page.
2. انقر على إنشاء بيانات الاعتماد > معرِّف عميل OAuth.
3. تصف الأقسام أدناه أنواع البرامج وطُرق إعادة التوجيه التي يتيحها خادم تفويض Google. اختَر نوع العميل المقترَح لتطبيقك وأدخِل اسمًا لعميل OAuth، ثم اضبط الحقول الأخرى في النموذج على النحو المناسب.

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

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

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

يستخدم الإصدار الثالث من YouTube Data API النطاقات التالية:

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

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

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

الخطوة 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. تعالج نقطة النهاية هذه البحث في الجلسة النشطة، وتصادق على المستخدم، وتحصل على موافقة المستخدم. يمكن الوصول إلى نقطة النهاية عبر طبقة المقابس الآمنة فقط، وترفض اتصالات HTTP (غير طبقة المقابس الآمنة).

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

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

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

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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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 وضبط المَعلمات التالية:

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

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

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

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

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

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

الاتصال بـ Google APIs

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

تجدر الإشارة إلى أنّ YouTube Live Streaming API لا تتيح تدفق حساب الخدمة. وبما أنّه لا تتوفّر طريقة لربط حساب الخدمة بحساب على YouTube، ستؤدي محاولات منح الإذن في الطلبات خلال هذا الإجراء إلى ظهور خطأ NoLinkedYouTubeAccount.

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

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

قد يبدو طلب نقطة نهاية liveBroadcasts.list (واجهة YouTube Live Streaming API) باستخدام عنوان HTTP Authorization: Bearer على النحو التالي. ملاحظة: يجب تحديد رمز الدخول الخاص بك:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

أمثلة على curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

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

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

لإعادة تحميل رمز دخول، يرسل تطبيقك طلب 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 للتطبيقات المحلية أفضل الممارسات الحالية لمجموعة مهندسي شبكة الإنترنت (IETF) العديد من أفضل الممارسات الموثَّقة هنا.