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

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

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

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

مكتبة برامج Google APIs وخدمات Google Identity

إذا كنت تستخدم مكتبة عميل Google APIs للغة JavaScript لإجراء طلبات معتمَدة إلى Google، عليك استخدام مكتبة Google Identity Services للغة JavaScript للتعامل مع مسار التفويض. ننصحك بشدة باستخدام نموذج الرمز في Google Identity Services، والذي يستند إلى مسار رمز التفويض الأكثر أمانًا مع PKCE.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الخطوة 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 مطلوب

معرّف العميل لتطبيقك يمكنك العثور على هذه القيمة في Cloud Console صفحة العملاء.
redirect_uri مطلوب

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

يُرجى العِلم أنّه يجب أن يتطابق المخطّط http أو https مع حالة الأحرف والشرطة المائلة الأخيرة (/).
response_type مطلوب

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

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

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

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

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

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