استخدام OAuth 2.0 للدخول إلى واجهات برمجة تطبيقات Google

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

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

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

الخطوات الأساسية

تتبع جميع التطبيقات نمطًا أساسيًا عند الدخول إلى واجهة برمجة تطبيقات Google باستخدام OAuth 2.0. على مستوى عالٍ، تتّبع خمس خطوات:

1- يمكنك الحصول على بيانات اعتماد OAuth 2.0 من Google API Console.

انتقِل إلى Google API Console للحصول على بيانات اعتماد OAuth 2.0، مثل معرِّف العميل وسر العميل المعروفين لكل من Google وتطبيقك. تختلف مجموعة القيم بناءً على نوع التطبيق الذي تنشئه. على سبيل المثال، لا يتطلّب تطبيق JavaScript استخدام واجهة برمجة تطبيقات سرّية، ولكنّه يتطلّب تطبيق خادم ويب.

يجب عليك إنشاء عميل OAuth مناسب للنظام الأساسي الذي سيتم تشغيل تطبيقك عليه، على سبيل المثال:

2- احصل على رمز الدخول من خادم تفويض Google.

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

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

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

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

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

3. افحص نطاقات الدخول التي منحها المستخدم.

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

قد لا يتطابق النطاق المضمّن في طلبك مع النطاق المضمّن في ردك حتى إذا منحك المستخدم جميع النطاقات المطلوبة. يُرجى الرجوع إلى وثائق كل Google API للاطّلاع على النطاقات المطلوبة للوصول. يمكن لواجهة برمجة التطبيقات ربط قيم سلسلة نطاق متعددة بنطاق وصول واحد، مع عرض سلسلة النطاق نفسها لجميع القيم المسموح بها في الطلب. مثال: قد تعرض Google People API نطاقًا يبلغ https://www.googleapis.com/auth/contacts عندما يطلب أحد التطبيقات مستخدمًا الحصول على نطاق https://www.google.com/m8/feeds/، بينما تتطلب طريقة Google People API people.updateContact نطاقًا ممنوحًا بقيمة https://www.googleapis.com/auth/contacts.

4. أرسِل رمز الدخول إلى واجهة برمجة التطبيقات.

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

لا تكون رموز الدخول صالحة إلا لمجموعة العمليات والمصادر الموضحة في scope من طلب الرمز المميز. على سبيل المثال، إذا تم إصدار رمز دخول لـ Google Calendar API، فلن يمنح هذا التطبيق إمكانية الدخول إلى واجهة برمجة تطبيقات جهات اتصال Google. ومع ذلك، يمكنك إرسال رمز الدخول هذا إلى واجهة برمجة تطبيقات "تقويم Google" عدة مرات لعمليات مماثلة.

5. أعِد تحميل رمز الدخول، إذا لزم الأمر.

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

السيناريوهات

تطبيقات خادم الويب

تتوافق نقطة نهاية Google OAuth 2.0 مع تطبيقات خادم الويب التي تستخدم لغات وأُطر عمل مثل PHP وجافا سكريبت وPython وRuby وASP.NET.

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

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

يرسل تطبيقك طلب رمز مميز إلى خادم تفويض Google، ويتلقى رمز تفويض، ويستبدل الرمز برمز مميز، ويستخدم الرمز المميز لاستدعاء نقطة نهاية Google API.

لمعرفة التفاصيل، يُرجى الاطِّلاع على استخدام OAuth 2.0 لتطبيقات خادم الويب.

التطبيقات المثبتة

تتوافق نقطة نهاية Google OAuth 2.0 مع التطبيقات التي يتم تثبيتها على الأجهزة مثل أجهزة الكمبيوتر والأجهزة الجوّالة والأجهزة اللوحية. عند إنشاء معرِّف عميل من خلال Google API Console، حدِّد أنّ هذا التطبيق هو التطبيق المُثبَّت، ثم اختَر Android أو تطبيق Chrome أو iOS أو Universal Windows Platform (UWP) أو تطبيق سطح المكتب كنوع التطبيق.

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

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

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

يرسل تطبيقك طلب رمز مميز إلى خادم تفويض Google، ويتلقى رمز تفويض، ويستبدل الرمز برمز مميز، ويستخدم الرمز المميز لاستدعاء نقطة نهاية Google API.

لمعرفة التفاصيل، يُرجى الاطِّلاع على استخدام OAuth 2.0 للتطبيقات المثبَّتة.

تطبيقات (جافا سكريبت) من جهة العميل

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

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

والنتيجة هي رمز دخول يجب على العميل التحقُّق منه قبل إدراجه في طلب Google API. عند انتهاء صلاحية الرمز المميز، يكرر التطبيق العملية.

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

لمعرفة التفاصيل، يُرجى الاطِّلاع على استخدام OAuth 2.0 للتطبيقات من جهة العميل.

التطبيقات على الأجهزة ذات الإدخال المحدود

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

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

يحصل المستخدم على عنوان URL والرمز من الجهاز، ثم ينتقل إلى جهاز أو كمبيوتر منفصل مع إمكانات إدخال أكثر ثراءً. يُطلق المستخدم متصفّحًا وينتقل إلى عنوان URL المحدّد ويسجّل الدخول ويُدخل الرمز.

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

تسجيل دخول المستخدم على جهاز منفصل يتضمّن متصفّحًا

لمعرفة التفاصيل، يُرجى الاطِّلاع على استخدام OAuth 2.0 للأجهزة.

حسابات الخدمة

يمكن لواجهات برمجة تطبيقات Google، مثل Prediction API وGoogle Cloud Storage، التصرف نيابة عن تطبيقك بدون الوصول إلى معلومات المستخدم. وفي هذه الحالات، يحتاج تطبيقك إلى إثبات هويته الخاصة لواجهة برمجة التطبيقات، ولكن ليس من الضروري الحصول على موافقة المستخدم. وبالمثل، في سيناريوهات المؤسسات، يمكن أن يطلب تطبيقك الوصول المفوَّض إلى بعض الموارد.

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

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

يستخدم تطبيق الخادم JWT لطلب رمز مميز من خادم تفويض Google، ثم يستخدم الرمز المميز لطلب نقطة نهاية واجهة برمجة تطبيقات Google. ولا يتم تضمين أي مستخدم.

لمعرفة التفاصيل، يُرجى الاطّلاع على مستندات حساب الخدمة.

حجم الرمز المميز

يمكن أن يختلف حجم الرموز المميزة، وفقًا للحدود التالية:

  • رموز التفويض: 256 بايت
  • رموز الدخول: 2048 بايت
  • الرموز المميزة لإعادة التحميل: 512 بايت

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

وتحتفظ Google بالحق في تغيير حجم الرمز المميّز في هذه الحدود، ويجب أن يتيح تطبيقك أحجام الرموز المميّزة المتغيّرة وفقًا لذلك.

تحديث انتهاء صلاحية الرمز المميز

يجب كتابة الرمز لتوقّع احتمال عدم عمل رمز مميّز لإعادة التحميل. قد يتوقف الرمز المميز للتحديث عن العمل لأحد الأسباب التالية:

يتم إصدار رمز مميز لإعادة التحميل بعد 7 أيام لمشروع Google Cloud Platform الذي يحتوي على شاشة موافقة OAuth تم ضبطها لنوع مستخدم خارجي وحالة النشر "للاختبار"، ما لم تكن نطاقات OAuth الوحيدة المطلوبة سوى مجموعة فرعية من الاسم وعنوان البريد الإلكتروني والملف الشخصي للمستخدم (من خلال نطاقات userinfo.email, userinfo.profile, openid، أو ما يعادلها من نطاقات OpenID Connect).

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

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

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

التعامل مع سياسات التحكُّم في الجلسات لمؤسسات Google Cloud Platform (GCP)

قد يطلب مشرفو المؤسسات في برنامج "شركاء Google المعتمدون" إعادة مصادقة المستخدمين باستمرار أثناء وصولهم إلى موارد Google Cloud Platform، باستخدام ميزة التحكم في جلسة Google Cloud . تؤثّر هذه السياسة في إمكانية الوصول إلى Google Cloud Console وGoogle Cloud SDK (المعروفة أيضًا باسم gcloud CLI) وأي تطبيق OAuth تابع لجهة خارجية يتطلب نطاق Cloud Platform. إذا كان لدى المستخدم سياسة تحكُّم في الجلسة سارية، فعند انتهاء صلاحية مدة الجلسة، ستظهر طلبات البيانات من واجهة برمجة التطبيقات كما يحدث عند إبطال الرمز المميز لإعادة التحميل. وسيتعذّر الاستدعاء مع ظهور نوع الخطأ invalid_grant، ويمكن استخدام الحقل error_subtype للتمييز بين الرمز المميّز الذي تم إبطاله والإخفاق بسبب سياسة التحكم في الجلسة (على سبيل المثال، "error_subtype": "invalid_rapt"). ويمكن أن تكون فترات الجلسة محدودة جدًا (ويمكن أن تكون فترة عمل كل ساعتيْن متتاليتين، ويمكن أن تتم عملية إعادة التشغيل بعد ساعة واحدة أو أكثر).

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

لمزيد من المعلومات حول كيفية مساعدة عملائك في نشر هذه الميزة، يُرجى الرجوع إلى مقالة المساعدة التي تركّز على المشرف.

مكتبات العملاء

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