استخدام 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 Connect.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تتوافق نقطة نهاية Google OAuth 2.0 مع تطبيقات خادم الويب التي تستخدم اللغات وأُطر العمل مثل PHP وJava و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 للتطبيقات المثبّتة.

تطبيقات (JavaScript) من جهة العميل

تتوافق نقطة نهاية Google OAuth 2.0 مع تطبيقات JavaScript التي تعمل في المتصفِّح.

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

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

يرسل تطبيق JS طلبًا للرمز المميّز إلى خادم تفويض 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 API نيابةً عن حساب الخدمة، وليس عليك موافقة المستخدم. (في السيناريوهات التي لا تنتمي إلى حساب خدمة، يطلب تطبيقك Google APIs نيابةً عن المستخدمين النهائيين، وفي بعض الأحيان تكون موافقة المستخدم مطلوبة).

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

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

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

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

يمكن أن يختلف حجم الرموز المميّزة إلى الحدود التالية:

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

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

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

إعادة تحميل صلاحية الرمز المميز

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

  • أجرى المستخدم إبطال حق وصول تطبيقك.
  • لم يتم استخدام الرمز المميز لإعادة التحميل لمدة ستة أشهر.
  • غيَّر المستخدم كلمات المرور ويحتوي الرمز المميز لإعادة التحميل على نطاقات Gmail.
  • تجاوز حساب المستخدم الحد الأقصى لعدد الرموز المميزة لإعادة التحميل (المباشرة) التي تم منحها.
  • ينتمي المستخدم إلى مؤسسة Google Cloud Platform لديها سياسات تحكُّم في الجلسة سارية.

يتم إصدار رمز مميّز لإعادة التحميل ستنتهي فيه صلاحية 7 أيام لمشروع Google Cloud Platform الذي يتضمّن شاشة موافقة OAuth لنوع مستخدم خارجي وحالة نشر ""Testing".

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

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

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

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

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

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

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

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

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