استخدام OAuth 2.0 لتطبيقات الويب JavaScript

يوضح هذا المستند كيفية تنفيذ تفويض OAuth 2.0 للوصول إلى YouTube Data API من تطبيق ويب JavaScript. يسمح OAuth 2.0 للمستخدمين بإجراء ما يلي: مشاركة بيانات محددة مع أحد التطبيقات مع الاحتفاظ بأسماء المستخدمين وكلمات المرور وغيرها خصوصية المعلومات. على سبيل المثال، يمكن لأحد التطبيقات استخدام OAuth 2.0 للحصول على إذن تحميل فيديوهات إلى قناة المستخدم على YouTube

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

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

مكتبة عملاء Google APIs وخدمات Google Identity

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

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

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

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

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

المناظير
https://www.googleapis.com/auth/youtubeإدارة حسابك في YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creatorالاطّلاع على قائمة بأعضاء القناة النشطين حاليًا ومستواهم الحالي وتاريخ انضمامهم
https://www.googleapis.com/auth/youtube.force-sslالاطّلاع على فيديوهاتك على YouTube وتقييماتها وتعليقاتها وترجماتها وكذلك تعديلها وحذفها نهائيًا
https://www.googleapis.com/auth/youtube.readonlyعرض حسابك في YouTube
https://www.googleapis.com/auth/youtube.uploadإدارة فيديوهات YouTube
https://www.googleapis.com/auth/youtubepartnerعرض وإدارة أصولك والمحتوى المرتبط بها على YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditعرض معلومات خاصة عن قناتك على YouTube ذات صلة أثناء عملية تدقيق شريك YouTube

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

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

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

الخطوة 1: إعادة التوجيه إلى خادم OAuth 2.0 من Google

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

نقاط نهاية OAuth 2.0

إنشاء عنوان URL لطلب الوصول من نقطة نهاية OAuth 2.0 من Google على https://accounts.google.com/o/oauth2/v2/auth يمكن الوصول إلى نقطة النهاية هذه عبر HTTPS. يتم رفض اتصالات HTTP العادية.

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

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

معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في API Console Credentials page

redirect_uri مطلوب

تحدد المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد إكمال المستخدم لعملية مسار التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المصرّح بها لإعادة التوجيه عميل OAuth 2.0، الذي هيأته في نافذة حساب العميل API Console Credentials pageوإذا لم تتطابق هذه القيمة مع معرّف الموارد المنتظم (URI) المعتمَد لإعادة التوجيه لمعرّف client_id المقدَّم، ستحصل على معرّف موارد منتظم (URI) لإعادة التوجيه. خطأ redirect_uri_mismatch.

تجدر الإشارة إلى أنّ المخطَّط http أو https، وحالة الأحرف، والشرطة المائلة اللاحقة ('/') يجب أن تتطابق جميعها.

response_type مطلوب

تحتاج تطبيقات JavaScript إلى ضبط قيمة المَعلمة على token. هذا النمط توجه خادم تفويض Google لإرجاع رمز الدخول زوج name=value في معرّف الجزء من معرّف الموارد المنتظم (URI) (#) الذي تشير إليه ستتم إعادة توجيه المستخدم بعد إكمال عملية التفويض.

scope مطلوب

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

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

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

المناظير
https://www.googleapis.com/auth/youtubeإدارة حسابك في YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creatorالاطّلاع على قائمة بأعضاء القناة النشطين حاليًا ومستواهم الحالي وتاريخ انضمامهم
https://www.googleapis.com/auth/youtube.force-sslالاطّلاع على فيديوهاتك على YouTube وتقييماتها وتعليقاتها وترجماتها وكذلك تعديلها وحذفها نهائيًا
https://www.googleapis.com/auth/youtube.readonlyعرض حسابك في YouTube
https://www.googleapis.com/auth/youtube.uploadإدارة فيديوهات YouTube
https://www.googleapis.com/auth/youtubepartnerعرض وإدارة أصولك والمحتوى المرتبط بها على YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditعرض معلومات خاصة عن قناتك على YouTube ذات صلة أثناء عملية تدقيق شريك YouTube

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

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

state مقترَح

تحدِّد هذه السياسة أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض. يعرض الخادم القيمة الدقيقة التي ترسلها كزوج name=value في معرّف جزء عنوان URL (#) من redirect_uri بعد موافقة المستخدم على طلب اشتراكك أو رفضه طلب وصول.

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

include_granted_scopes اختياريّ

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

login_hint اختياريّ

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

اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرِّف sub، وهو مكافئ لمعرّف Google للمستخدم.

prompt اختياريّ

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

القيم المتاحة:

none لا تعرض أي شاشات مصادقة أو موافقة. يجب ألا يتم تحديدها باستخدام القيم الأخرى.
consent اطلب من المستخدم الموافقة.
select_account اطلب من المستخدم اختيار حساب.

نموذج لإعادة التوجيه إلى خادم تفويض Google

يطلب نموذج عنوان URL أدناه الوصول بلا إنترنت (access_type=offline) إلى نطاق يسمح بالوصول إلى العرض حساب المستخدم على YouTube. فهو يستخدم تفويضًا متزايدًا لضمان أن رمز الدخول الجديد يشمل أي نطاقات منحها المستخدم سابقًا وصول التطبيق. يضبط عنوان URL أيضًا قيمًا للحقل redirect_uri وresponse_type و معلمات client_id وكذلك state . يحتوي عنوان URL على فواصل أسطر ومسافات لسهولة القراءة.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

بعد إنشاء عنوان URL للطلب، أعِد توجيه المستخدم إليه.

نموذج رمز JavaScript

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

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

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

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

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

الأخطاء

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

admin_policy_enforced

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

disallowed_useragent

يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن غير مسموح به من قِبل Google سياسات OAuth 2.0.

Android

قد تظهر رسالة الخطأ هذه لمطوِّري تطبيقات Android عند فتح طلبات الحصول على إذن في android.webkit.WebView وبدلاً من ذلك، على المطوّرين استخدام مكتبات Android مثل تسجيل الدخول باستخدام حساب Google لنظام التشغيل Android أو OpenID Foundation تطبيق AppAuth لنظام التشغيل Android

قد يواجه مطوّرو الويب هذا الخطأ عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 في Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي نظام التشغيل، والذي يشمل كلاً من Android App Links المستخدم أو تطبيق المتصفح الافتراضي. تشير رسالة الأشكال البيانية علامات التبويب المخصَّصة في Android المكتبة خيارًا متوافقًا.

iOS

قد يواجه مطوّرو iOS وmacOS هذا الخطأ عند فتح طلبات التفويض في WKWebView وبدلاً من ذلك، يجب أن يستخدم المطوّرون مكتبات iOS مثل تسجيل الدخول باستخدام حساب Google لأجهزة iOS أو OpenID Foundation تطبيق AppAuth لنظام التشغيل iOS

قد يظهر هذا الخطأ لمطوِّري الويب عندما يفتح تطبيق iOS أو macOS رابط ويب عامًا في وكيل مستخدم مضمن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 في Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي نظام التشغيل، والذي يشمل كلاً من الروابط العامة المستخدم أو تطبيق المتصفح الافتراضي. تشير رسالة الأشكال البيانية SFSafariViewController المكتبة خيارًا متوافقًا.

org_internal

معرِّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من إمكانية الوصول إلى حسابات Google في محددة مؤسسة Google Cloud: لمزيد من المعلومات حول خيار التهيئة هذا، راجع نوع المستخدِم في مقالة المساعدة "إعداد شاشة طلب الموافقة المتعلقة ببروتوكول OAuth".

invalid_client

المصدر الذي تم تقديم الطلب منه غير مسموح به لهذا العميل. عرض origin_mismatch

invalid_grant

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

origin_mismatch

قد لا يكون مخطط و/أو نطاق و/أو منفذ JavaScript الذي ينشأ عن طلب التفويض تطابق معرّف موارد منتظم (URI) لمصدر JavaScript معتمد ومسجَّل لمعرّف عميل OAuth. تم منح الإذن بالمراجعة مصادر JavaScript في Google API Console Credentials page

redirect_uri_mismatch

redirect_uri الذي تم تمريره في طلب التفويض لا يتطابق مع القيمة المُصرّح بها. معرّف الموارد المنتظم (URI) لإعادة التوجيه لمعرّف عميل OAuth. مراجعة معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه في Google API Console Credentials page

قد لا يكون مخطط و/أو نطاق و/أو منفذ JavaScript الذي ينشأ عن طلب التفويض تطابق معرّف موارد منتظم (URI) لمصدر JavaScript معتمد ومسجَّل لمعرّف عميل OAuth. تعليق مصادر JavaScript المسموح بها في Google API Console Credentials page

قد تشير المعلَمة redirect_uri إلى مسار OAuth خارج النطاق (OOB) الذي يتضمن تم إيقافها ولم تعد متاحة. ارجع إلى دليل نقل البيانات لتعديل التكامل.

invalid_request

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

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

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

نقاط نهاية OAuth 2.0

يرسل خادم OAuth 2.0 استجابة إلى redirect_uri المحددة في طلب رمز الدخول.

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

  • استجابة رمز الدخول:

    https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

    بالإضافة إلى المعلمة access_token، تتضمن سلسلة التجزئة أيضًا يحتوي على المعلمة token_type، التي يتم تعيينها دائمًا على Bearer، والمعلمة expires_in، التي تحدد فترة بقاء الرمز المميّز بالثواني. إذا تم تحديد مَعلمة state في طلب رمز الدخول، يتم تضمين قيمته أيضًا في الاستجابة.

  • ظهور خطأ:
    https://oauth2.example.com/callback#error=access_denied

نموذج استجابة خادم OAuth 2.0

يمكنك اختبار هذا المسار بالنقر على نموذج عنوان URL التالي، الذي يطلب إذن بالقراءة فقط لعرض البيانات الوصفية للملفات في Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

بعد إكمال مسار OAuth 2.0، ستتم إعادة توجيهك إلى http://localhost/oauth2callback سيؤدي عنوان URL هذا إلى خطأ واحد (404 NOT FOUND) ما لم يتصادف أن يعرض جهازك المحلي ملفًا في هذا العنوان. توفر الخطوة التالية مزيدًا من التفاصيل حول المعلومات التي يتم عرضها في معرّف موارد منتظم (URI) عندما تتم إعادة توجيه المستخدم إلى تطبيقك مرة أخرى.

الاتصال بـ Google APIs

نقاط نهاية OAuth 2.0

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

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

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

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

اتصال 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

نموذج رمز JavaScript

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

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

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

المثال الكامل

نقاط نهاية OAuth 2.0

يوضح نموذج الرمز هذا كيفية إكمال مسار OAuth 2.0 في JavaScript بدون استخدام مكتبة برامج Google APIs للغة JavaScript. يكون الرمز مخصصًا لصفحة HTML تعرض زرًا جرِّب طلب واجهة برمجة تطبيقات. عند النقر على الزر، يتحقق الرمز البرمجي لمعرفة ما إذا كانت الصفحة قد خزنت رمز الدخول إلى واجهة برمجة التطبيقات في مساحة التخزين المحلية في المتصفّح. في هذه الحالة، سيتم تنفيذ طلب البيانات من واجهة برمجة التطبيقات. وإلا، يؤدي إلى بدء تدفق OAuth 2.0.

بالنسبة إلى مسار OAuth 2.0، تتّبع الصفحة الخطوات التالية:

  1. وهو يوجه المستخدم إلى خادم OAuth 2.0 من Google، والذي يطلب الوصول إلى نطاق واحد (https://www.googleapis.com/auth/youtube.force-ssl).
  2. بعد منح (أو رفض) إذن الوصول إلى نطاق واحد أو أكثر من النطاقات المطلوبة، تتم إعادة توجيه المستخدم إلى الصفحة الأصلية، التي تحلل رمز الدخول من سلسلة معرف الجزء.
  3. تستخدم الصفحة رمز الدخول لإجراء نموذج طلب البيانات من واجهة برمجة التطبيقات.

    يستدعي طلب البيانات من واجهة برمجة التطبيقات هذا طريقة channels.list في YouTube Data API. لاسترداد بيانات حول قناة المستخدم المصرح لها على YouTube.

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

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

لتشغيل هذا الرمز محليًا، يجب ضبط قيم للسمة YOUR_CLIENT_ID متغيرات YOUR_REDIRECT_URI التي تتوافق مع بيانات الاعتماد الخاصة بالتفويض. المتغيّر YOUR_REDIRECT_URI على عنوان URL نفسه الذي يتم عرض الصفحة فيه يجب أن تتطابق القيمة تمامًا مع إحدى معرفات الموارد المنتظمة (URI) لإعادة التوجيه المسموح بها لعميل OAuth 2.0، والتي هيأتها في API Console Credentials pageفي حال حذف لا تتطابق هذه القيمة مع معرّف موارد منتظم (URI) معتمَد، ستحصل على redirect_uri_mismatch. خطأ. ينبغي أن يحتوي مشروعك أيضًا على فعّلت واجهة برمجة التطبيقات المناسبة لهذا الطلب.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var fragmentString = location.hash.substring(1);
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0 && params['state']) {
    if (params['state'] == localStorage.getItem('state')) {
      localStorage.setItem('oauth2-test-params', JSON.stringify(params) );

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null);
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
                  'state': state,
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

قواعد التحقّق من مصدر JavaScript

يطبِّق محرّك بحث Google قواعد التحقّق التالية على مصادر JavaScript للمساعدة في ذلك. يحافظ المطورون على أمان تطبيقاتهم. يجب أن تتقيّد مصادر JavaScript بهذه القواعد. راجِع الفقرة 3 من معيار RFC 3986 للاطّلاع على النطاق والمضيف والمخطط أدناه.

قواعد التحقّق من الصحة
المخطط

يجب أن تستخدم أصول JavaScript مخطط HTTPS، وليس HTTP العادي. معرفات الموارد المنتظمة (URI) للمضيف المحلي تُستثنى من هذه القاعدة (بما في ذلك معرّفات الموارد المنتظمة (URI) لعنوان IP للمضيف المحلي).

المضيف

لا يمكن للمضيفين أن يكونوا عناوين IP غير معدّلة. تُستثنى من هذه القاعدة عناوين IP للمضيف المحلي.

النطاق
  • نطاقات المستوى الأعلى للمضيف (نطاقات المستوى الأعلى) يجب أن ينتمي إلى قائمة اللاحقات العلنية.
  • لا يمكن أن تكون نطاقات المضيف “googleusercontent.com”.
  • لا يمكن أن تحتوي مصادر JavaScript على نطاقات اختصار لعناوين URL (مثل goo.gl). ما لم يكن التطبيق يملك النطاق.
  • معلومات المستخدم

    لا يمكن أن تحتوي أصول JavaScript على المكوِّن الفرعي لـ userinfo.

    المسار

    لا يمكن أن تحتوي أصول JavaScript على مكوّن المسار.

    طلب بحث

    لا يمكن أن تحتوي مصادر JavaScript على مكوّن طلب البحث.

    الجزء

    لا يمكن أن تحتوي أصول JavaScript على المكوِّن.

    الشخصيات لا يمكن أن تحتوي مصادر JavaScript على أحرف معيّنة، بما في ذلك:
    • أحرف البدل ('*')
    • أحرف ASCII غير قابلة للطباعة
    • ترميزات النسبة المئوية غير صالحة (أي ترميز نسبة مئوية لا يتبع ترميز عنوان URL) شكل علامة نسبة مئوية متبوعة برقمين سداسيين)
    • أحرف فارغة (حرف فارغ مرمّز، مثل %00, %C0%80)

    التفويض التزايدي

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

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

    في هذه الحالة، أثناء تسجيل الدخول، قد لا يحتاج التطبيق إلى الوصول إلى وأي نطاقات. ومع ذلك، إذا حاول المستخدم تقييم فيديو، أضِف فيديو إلى قائمة التشغيل أو تنفيذ إجراء آخر على YouTube، قد يطلب التطبيق الوصول إلى النطاق https://www.googleapis.com/auth/youtube.force-ssl. وبالمثل، يمكن للتطبيق طلب الوصول إلى نطاق https://www.googleapis.com/auth/calendar إذا حاول المستخدم لإضافة حدث في التقويم.

    تنطبق القواعد التالية على رمز الدخول الذي يتم الحصول عليه من تفويض متزايد:

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

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

    نقاط نهاية OAuth 2.0

    في هذا المثال، يطلب تطبيق الاتصال الوصول لاسترداد بيانات YouTube Analytics الخاصة بالمستخدم بالإضافة إلى أي حق وصول آخر سبق أن تم منحه للتطبيق.

    لإضافة نطاقات إلى رمز دخول حالي، يجب تضمين include_granted_scopes في طلبك المُرسَل إلى خادم OAuth 2.0 في Google.

    يوضح مقتطف الرمز التالي كيفية إجراء ذلك. يفترض المقتطف أنك خزّنت النطاقات التي يكون رمز الدخول الخاص بها صالحًا في مساحة التخزين المحلية للمتصفِّح. ( يخزِّن رمز المثال الكامل قائمة بالنطاقات التي يتوفّر لها رمز دخول. صالح من خلال ضبط السمة oauth2-test-params.scope في الصفحة المحلية للمتصفّح storage.)

    يقارن المقتطف النطاقات التي يكون رمز الدخول لها صالحًا للنطاق الذي تريد استخدامه. لطلب بحث معين. وإذا لم يغطِ رمز الدخول هذا النطاق، سيبدأ مسار OAuth 2.0. الدالة oauth2SignIn هي نفسها الدالة التي تم توفيرها هنا الخطوة 2 (ويتم توفيرها لاحقًا في علامة التبويب إكمال مثال).

    var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    
    var current_scope_granted = false;
    if (params.hasOwnProperty('scope')) {
      var scopes = params['scope'].split(' ');
      for (var s = 0; s < scopes.length; s++) {
        if (SCOPE == scopes[s]) {
          current_scope_granted = true;
        }
      }
    }
    
    if (!current_scope_granted) {
      oauth2SignIn(); // This function is defined elsewhere in this document.
    } else {
      // Since you already have access, you can proceed with the API request.
    }

    إبطال رمز مميّز

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

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

    نقاط نهاية OAuth 2.0

    لإبطال رمز مميّز آليًا، يطلب تطبيقك 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 مع مع رمز خطأ.

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

    function revokeAccess(accessToken) {
      // Google's OAuth 2.0 endpoint for revoking access tokens.
      var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
    
      // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
      var form = document.createElement('form');
      form.setAttribute('method', 'post');
      form.setAttribute('action', revokeTokenEndpoint);
    
      // Add access token to the form so it is set as value of 'token' parameter.
      // This corresponds to the sample curl request, where the URL is:
      //      https://oauth2.googleapis.com/revoke?token={token}
      var tokenField = document.createElement('input');
      tokenField.setAttribute('type', 'hidden');
      tokenField.setAttribute('name', 'token');
      tokenField.setAttribute('value', accessToken);
      form.appendChild(tokenField);
    
      // Add form to page and submit it to actually revoke the token.
      document.body.appendChild(form);
      form.submit();
    }

    تطبيق ميزة "الحماية العابرة للحساب"

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

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