تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

استخدام 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 Identity لمعالجة مسار OAuth 2.0. يُرجى الاطّلاع على نموذج الرمز المميز الخاص بخدمات إدارة هوية Google، والذي يستند إلى مسار المنح الضمني لـ OAuth 2.0.

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

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

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

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

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

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

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

Go to the Credentials page.
انقر على إنشاء بيانات الاعتماد > معرِّف عميل OAuth.
اختَر نوع تطبيق تطبيق الويب.
أكمل النموذج. يجب أن تحدّد التطبيقات التي تستخدم 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 API على قائمة كاملة بالنطاقات التي قد تستخدمها للوصول إلى واجهات 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

مطلوب

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

redirect_uri

مطلوب

تحدِّد هذه السياسة الموضع الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد أن يكمل المستخدم مسار التفويض. يجب أن تتطابق القيمة بشكل تام مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه لعميل OAuth 2.0، الذي ضبطته في API Console Credentials pageفي جهاز العميل. إذا لم تتطابق هذه القيمة مع معرّف الموارد المنتظم (URI) المعتمَد لإعادة التوجيه لعنوان client_id المقدَّم، ستظهر لك رسالة الخطأ 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 Connect للاطّلاع على مثال عن كيفية إنشاء رمز مميّز state وتأكيده.

ملاحظة مهمة: يجب أن يمنع عميل OAuth CSRF كما هو موضح في مواصفات OAuth2 . ويتم ذلك عن طريق استخدام مَعلمة state للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض.

include_granted_scopes

اختياريّ

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

enable_granular_consent

اختياريّ

وتكون القيمة التلقائية هي true. أمّا في حال ضبط السياسة على false، فسيتم إيقاف مزيد من أذونات حساب Google الدقيقة لمعرّفات عملاء OAuth التي تم إنشاؤها قبل 2019. ولن يكون هناك أي تأثير في معرّفات عملاء OAuth الجديدة، إذ يتم دائمًا تفعيل المزيد من الأذونات الدقيقة لهذه المعرّفات.

عندما يفعّل محرّك بحث Google أذونات دقيقة لأحد التطبيقات، لن يكون لهذه المَعلمة أي تأثير بعد ذلك.

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`

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

Android

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

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

iOS

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

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

يرسل خادم 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

بعد حصول تطبيقك على رمز الدخول، يمكنك استخدام هذا الرمز لإجراء اتصالات بواجهة برمجة تطبيقات Google نيابةً عن حساب مستخدم معيّن إذا تم منح نطاقات الوصول التي تطلبها واجهة برمجة التطبيقات. لإجراء ذلك، يمكنك تضمين رمز الدخول في طلب إلى واجهة برمجة التطبيقات عن طريق تضمين معلَمة طلب البحث 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) باستخدام عنوان HTTP Authorization: Bearer على النحو التالي. ملاحظة: يجب تحديد رمز الدخول الخاص بك:

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، تتّبع الصفحة الخطوات التالية:

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

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

ويمكنك إبطال إمكانية الوصول إلى التطبيق من خلال صفحة الأذونات في حسابك على 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

لإبطال رمز مميّز آليًا، يرسل تطبيقك طلبًا إلى 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();
}

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

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

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

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

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

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

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

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

نقاط نهاية OAuth 2.0

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

نموذج رمز JavaScript

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

الأخطاء

admin_policy_enforced

disallowed_useragent

Android

iOS

org_internal

invalid_client

invalid_grant

origin_mismatch

redirect_uri_mismatch

invalid_request

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

نقاط نهاية OAuth 2.0

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

الاتصال بـ Google APIs

نقاط نهاية OAuth 2.0

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

أمثلة على curl

نموذج رمز JavaScript

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

نقاط نهاية OAuth 2.0

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

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

نقاط نهاية OAuth 2.0

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

نقاط نهاية OAuth 2.0

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_client`

`invalid_grant`

`origin_mismatch`

`redirect_uri_mismatch`

`invalid_request`

أمثلة على `curl`