استخدام 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 باستخدام OAuth 2.0. على مستوى عالٍ، اتّبعت خمس خطوات:

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

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

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

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

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

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

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

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

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

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

قد لا يتطابق النطاق المضمّن في طلبك مع النطاق المضمّن في ردك، حتى حتى إذا منح المستخدم جميع النطاقات المطلوبة. يُرجى مراجعة المستندات لكل واجهة برمجة تطبيقات من Google للنطاقات المطلوبة للوصول. يمكن لواجهة برمجة التطبيقات ربط قيم متعددة لسلسلة النطاق بنطاق واحد من أذونات الوصول، ما يؤدي إلى عرض سلسلة النطاق نفسها لجميع القيم المسموح بها في الطلب. على سبيل المثال: قد تعرض واجهة برمجة التطبيقات لتطبيق الأشخاص من Google نطاقًا يبلغ 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 Contacts API. ومع ذلك، يمكنك إرسال رمز الدخول هذا إلى Google Calendar API عدة مرات للعمليات المشابهة.

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

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

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

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

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

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

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

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

لمعرفة التفاصيل، يُرجى الاطّلاع على استخدام بروتوكول 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.

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

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

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

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

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

يرسل تطبيق JavaScript طلب رمز مميّز إلى خادم تفويض Google
 ويتلقّى رمزًا مميّزًا ويتحقّق من صحة الرمز المميّز ويستخدم الرمز المميّز لطلب نقطة نهاية Google API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الحد الأقصى المسموح به حاليًا هو 50 رمزًا مميزًا لإعادة التحميل لكل حساب 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 CLI) وأي تطبيق OAuth تابع لجهة خارجية يتطلب نطاق Cloud Platform. إذا كان المستخدم لديه سياسة للتحكم في الجلسة، يتم تنفيذ ذلك عند انتهاء صلاحية مدة الجلسة، وستظهر طلبات البيانات من واجهة برمجة التطبيقات بشكل مشابه لما يحدث عند إبطال الرمز المميز لإعادة التحميل، وسيتعذّر الاتصال مع ظهور نوع الخطأ invalid_token، ويمكن استخدام نوع الخطأ الفرعي للتمييز بين رمز إبطال مميز وإخفاق بسبب سياسة التحكم في الجلسة. ونظرًا لأن فترات الجلسات يمكن أن تكون محدودة جدًا (بين ساعة واحدة و24 ساعة)، يجب التعامل مع هذا السيناريو بشكل أنيق من خلال إعادة تشغيل جلسة المصادقة.

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

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

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

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