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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ms-app://YOUR_APP_PACKAGE_SID

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

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

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

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

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

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

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

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

تتيح Google استخدام بروتوكول مفتاح الحماية لتبادل الرموز (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 (غير SSL).

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

أمثلة على عناوين 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.readonly&
 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.readonly&
 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&
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"
}

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

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

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

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

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

على سبيل المثال، يشير نموذج الرد التالي لرمز الدخول إلى أنّ المستخدم قد منح تطبيقك الإذن بالاطّلاع على فيديوهات المستخدم وتقييماتها وتعليقاتها وترجماتها على YouTube وتعديلها وحذفها نهائيًا:

  {
    "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 API (على سبيل المثال، عند استدعاء YouTube Data API).

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

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

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

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

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

أمثلة على curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&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&
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 مع رمز خطأ.

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

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

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

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

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

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

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