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

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

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

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

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

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

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

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

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

  • بالنسبة إلى تطبيقات Android، استخدِم Android.
  • بالنسبة إلى تطبيقات iOS وmacOS، استخدِم نوع عميل iOS.
  • code بالنسبة إلى تطبيقات الويب من جهة الخادم أو تطبيقات الويب JavaScript، استخدِم نوع عميل تطبيق الويب. لا تستخدِم نوع العميل هذا لأي تطبيق آخر، مثل التطبيقات الأصلية أو تطبيقات الأجهزة الجوّالة.
  • chrome_extension بالنسبة إلى إضافات Chrome ، استخدِم نوع عميل إضافة Chrome.
  • tv بالنسبة إلى الأجهزة التي تتطلّب إدخال بيانات محدودة، مثل أجهزة التلفزيون أو الأجهزة المضمّنة، استخدِم نوع عميل أجهزة التلفزيون والأجهزة التي تتطلّب إدخال بيانات محدودة.
  • host بالنسبة إلى التفاعلات من خادم إلى خادم، استخدِم حسابات الخدمة. لا يلزم توفُّر معرّف عميل OAuth.

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

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

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

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

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

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

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

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

قد لا يتطابق النطاق المضمّن في طلبك مع النطاق المضمّن في ردّك، حتى إذا منح المستخدم جميع النطاقات المطلوبة. يُرجى الرجوع إلى مستندات كل 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 API في عنوان طلب تفويض HTTP. يمكن إرسال الرموز المميزة كمعلَمات لسلسلة طلب البحث في عنوان URI، ولكن لا ننصح بذلك، لأنّ معلَمات URI يمكن أن تظهر في ملفات السجل غير الآمنة تمامًا. من الممارسات الجيدة في REST أيضًا تجنُّب إنشاء أسماء غير ضرورية لمعلَمات URI.

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

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

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

Scenarios

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يرسل تطبيق 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 APIs، مثل Prediction API وGoogle Cloud Storage، نيابةً عن تطبيقك بدون الوصول إلى معلومات المستخدم. في هذه الحالات، يحتاج تطبيقك إلى إثبات هويته لواجهة برمجة التطبيقات، ولكن لا يلزم الحصول على موافقة المستخدم. وبالمثل، في سيناريوهات المؤسسات، يمكن لتطبيقك طلب وصول مفوَّض إلى بعض الموارد.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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