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

استخدام OAuth 2.0 لتطبيقات الويب من جهة العميل

يوضح هذا المستند كيفية تنفيذ تفويض 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

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

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 على رابط بالنطاقات التي قد تستخدمها للوصول إلى 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 وتأكيده.

ملاحظة مهمة: يجب أن يمنع عميل 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، يتضمَّن فواصل أسطر والمسافات لسهولة القراءة. طلبات عنوان URL الوصول إلى نطاق يسمح باسترداد بيانات المستخدم على YouTube. يستخدم أزرار (include_granted_scopes=true) للتأكد من أن رمز الدخول الجديد أي نطاقات منحها المستخدم سابقًا إمكانية الوصول إلى التطبيق. غير ذلك يتم تعيين المعلمات أيضًا في المثال.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 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، يجب التأكد من أن تتطابق 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.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 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 Live Streaming API).

ملاحظة: لا تتيح YouTube Live Streaming API مسار حساب الخدمة. منذ ذلك الحين هي ليست طريقة لربط حساب الخدمة بحساب YouTube، تحاول السماح بالطلبات باستخدام إلى ظهور خطأ NoLinkedYouTubeAccount.

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

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

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

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

نموذج رمز JavaScript

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

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

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,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).
بعد منح (أو رفض) إذن الوصول إلى نطاق واحد أو أكثر من النطاقات المطلوبة، تتم إعادة توجيه المستخدم إلى الصفحة الأصلية، التي تحلل رمز الدخول من سلسلة معرف الجزء.
تستخدم الصفحة رمز الدخول لإجراء نموذج طلب البيانات من واجهة برمجة التطبيقات.

يستدعي طلب البيانات من واجهة برمجة التطبيقات هذا liveBroadcasts.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/liveBroadcasts?part=id,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 يدعم التفويض التزايدي. وتتيح لك هذه الميزة طلب النطاقات حسب الحاجة. إذا منح المستخدم إذنًا للنطاق الجديد، فيعرض رمز تفويض ربما يكون مقابل رمز مميز يحتوي على جميع النطاقات التي منحها المستخدم المشروع.

على سبيل المثال، لنفترض أن أحد التطبيقات يسترد بيانات قناة المستخدم التي تمت مصادقتها على YouTube وكذلك تتيح للمستخدم استرداد بيانات YouTube Analytics من خلال عملية خاصة. وفي هذه الحالة، عند تسجيل الدخول قد يطلب التطبيق إذن الوصول إلى https://www.googleapis.com/auth/youtube.force-ssl فقط. النطاق. ومع ذلك، إذا حاول المستخدم الوصول إلى بيانات "إحصاءات Google" لقناته، يمكن للتطبيق أيضًا طلب الوصول إلى نطاق https://www.googleapis.com/auth/yt-analytics.readonly.

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

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

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

نقاط نهاية OAuth 2.0

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

لإضافة نطاقات إلى رمز دخول حالي، يجب تضمين 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();
}

استخدام OAuth 2.0 لتطبيقات الويب من جهة العميل

مكتبة عملاء 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`