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

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

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

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

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

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

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

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

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

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

يجب تفعيل واجهات 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. انقر على إنشاء عميل.
3. توضّح الأقسام التالية أنواع العملاء التي يتيحها خادم التفويض من Google. اختَر نوع العميل الذي يُنصح به لتطبيقك، وأدخِل اسمًا لعميل OAuth، واضبط الحقول الأخرى في النموذج حسب الاقتضاء.

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

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

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

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

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

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

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

الخطوة 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.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 https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

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

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

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

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

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

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

استدعاء Google APIs

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

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

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

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

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

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

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

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