استخدام 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 سرًا، ولكن يتطلبه تطبيق خادم الويب.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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