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

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

للبدء، يجب الحصول على بيانات اعتماد عميل OAuth 2.0 من Google API Console. بعد ذلك، يطلب تطبيق العميل رمز دخول من "خادم تفويض Google"، ويستخرج رمزًا مميزًا من الاستجابة، ويرسل الرمز المميّز إلى واجهة برمجة تطبيقات Google التي تريد الوصول إليها. لإجراء عرض توضيحي تفاعلي حول استخدام 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 مفتاحًا سريًا، على عكس تطبيق خادم الويب.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ويرسل تطبيقك طلب رمز مميّز إلى خادم تفويض 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. بعد انتهاء صلاحية رمز الدخول، يستخدم التطبيق الرمز المميّز لإعادة التحميل للحصول على رمز جديد.

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

لمعرفة التفاصيل، يُرجى الاطّلاع على استخدام 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. بعد انتهاء صلاحية رمز الدخول، يستخدم التطبيق الرمز المميّز لإعادة التحميل للحصول على رمز جديد.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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