تستخدم 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 للحصول على بيانات اعتماد OAuth 2.0، مثل معرِّف العميل وسر العميل، والتي تكون معروفة لكل من Google وتطبيقك. تختلف مجموعة القيم استنادًا إلى نوع التطبيق الذي تنشئه. على سبيل المثال، لا يتطلّب تطبيق JavaScript رمزًا سريًا، ولكن يتطلّب تطبيق خادم الويب ذلك.
يجب إنشاء عميل OAuth مناسب للمنصة التي سيتم تشغيل تطبيقك عليها، على سبيل المثال:
- بالنسبة إلى تطبيقات Android، استخدِم نوع التطبيق Android.
-
بالنسبة إلى تطبيقات iOS، استخدِم نوع التطبيق iOS.
- desktop_windows بالنسبة إلى التطبيقات المتوافقة مع الكمبيوتر المكتبي (مثل تطبيقات Windows أو macOS أو Linux أو أدوات واجهة سطر الأوامر)، استخدِم نوع التطبيق تطبيق متوافق مع الكمبيوتر المكتبي.
- code بالنسبة إلى تطبيقات الويب من جهة الخادم أو تطبيقات الويب التي تستخدم JavaScript، استخدِم نوع التطبيق تطبيق ويب. لا تستخدِم نوع التطبيق هذا لأي تطبيق آخر، مثل التطبيقات الأصلية أو تطبيقات الأجهزة الجوّالة.
- chrome_extension بالنسبة إلى إضافات Chrome، استخدِم نوع التطبيق إضافة Chrome.
- tv بالنسبة إلى الأجهزة ذات الإدخال المحدود، مثل أجهزة التلفزيون أو الأجهزة المضمّنة، استخدِم نوع التطبيق أجهزة التلفزيون والأجهزة ذات الإدخال المحدود.
- host بالنسبة إلى التفاعلات من خادم إلى خادم، استخدِم حسابات الخدمة. ولا يلزم توفّر معرّف عميل OAuth.
2. الحصول على رمز دخول من خادم التفويض في Google
قبل أن يتمكّن تطبيقك من الوصول إلى البيانات الخاصة باستخدام واجهة برمجة تطبيقات Google، يجب أن يحصل على رمز دخول يمنحه إذن الوصول إلى واجهة برمجة التطبيقات هذه. يمكن أن يمنح رمز الدخول الواحد درجات متفاوتة
من الوصول إلى واجهات برمجة تطبيقات متعددة. تتحكّم مَعلمة متغيّرة تُسمّى scope في مجموعة
الموارد والعمليات التي يسمح بها رمز الدخول. خلال طلب رمز الدخول، يرسل تطبيقك قيمة واحدة أو أكثر في المَعلمة scope.
هناك عدة طرق لتقديم هذا الطلب، وتختلف حسب نوع التطبيق الذي تنشئه. على سبيل المثال، قد يطلب تطبيق JavaScript رمز دخول باستخدام إعادة توجيه المتصفّح إلى Google، بينما يستخدم تطبيق مثبّت على جهاز لا يتضمّن متصفّحًا طلبات خدمة الويب. لمزيد من المعلومات حول كيفية تقديم الطلب، يُرجى الاطّلاع على Scenarios وأدلة الاستخدام المفصّلة لكل نوع من أنواع التطبيقات.
تتطلّب بعض الطلبات خطوة مصادقة يسجّل فيها المستخدم الدخول باستخدام حسابه على 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 APIs في عنوان طلب تفويض HTTP. يمكن إرسال الرموز المميّزة كمَعلمات لسلسلة طلبات البحث في معرّف الموارد المنتظم (URI)، ولكن لا ننصح بذلك، لأنّ مَعلمات معرّف الموارد المنتظم (URI) قد ينتهي بها الأمر في ملفات السجلّات غير الآمنة تمامًا. ومن أفضل ممارسات REST أيضًا تجنُّب إنشاء أسماء معلَمات URI غير ضرورية.
تكون رموز الدخول صالحة فقط لمجموعة العمليات والموارد الموضّحة في
scope لطلب الرمز المميّز. على سبيل المثال، إذا تم إصدار رمز مميّز للوصول إلى
Google Calendar API، لن يمنح ذلك إذن الوصول إلى Google Contacts API. ومع ذلك، يمكنك إرسال رمز الدخول هذا إلى Google Calendar API عدة مرات لإجراء عمليات مماثلة.
5- أعِد تحميل رمز الدخول، إذا لزم الأمر.
تكون مدة صلاحية رموز الدخول محدودة. إذا كان تطبيقك يحتاج إلى الوصول إلى Google APIs بعد انتهاء صلاحية رمز الدخول واحد، يمكنه الحصول على الرمز المميز لإعادة التحميل. يسمح الرمز المميز لإعادة التحميل لتطبيقك بالحصول على رموز الدخول الجديدة.
السيناريوهات
توضّح هذه السيناريوهات كيفية استخدام OAuth 2.0 لطلب رموز التفويض والحصول على رموز الدخول والرمز المميز لإعادة التحميل لأنواع مختلفة من التطبيقات.
تطبيقات خادم الويب
تتوافق نقطة نهاية Google OAuth 2.0 مع تطبيقات خادم الويب التي تستخدم لغات وأُطر عمل مثل PHP وJava وGo وPython وRuby وASP.NET.
يبدأ تسلسل التفويض عندما يعيد تطبيقك توجيه متصفّح إلى عنوان URL على Google، ويتضمّن عنوان URL معلمات طلب البحث التي تشير إلى نوع الوصول المطلوب. تتولّى Google مصادقة المستخدم واختيار الجلسة وموافقة المستخدم. والنتيجة هي رمز تفويض يمكن للتطبيق استبداله برمز دخول ورمز مميّز لإعادة التحميل.
يجب أن يخزّن التطبيق الرمز المميز لإعادة التحميل لاستخدامه في المستقبل، وأن يستخدم رمز الدخول للوصول إلى Google API. بعد انتهاء صلاحية رمز الدخول، يستخدم التطبيق الرمز المميز لإعادة التحميل للحصول على رمز جديد.
لمعرفة التفاصيل، يُرجى الاطّلاع على استخدام OAuth 2.0 لتطبيقات خادم الويب.
التطبيقات المثبتة
تتوافق نقطة نهاية Google OAuth 2.0 مع التطبيقات المثبّتة على أجهزة مثل أجهزة الكمبيوتر والأجهزة الجوّالة والأجهزة اللوحية. عند إنشاء معرّف عميل من خلال Google API Console، يجب تحديد أنّ هذا التطبيق مثبَّت، ثم اختيار Android أو إضافة Chrome أو iOS أو تطبيق متوافق مع الكمبيوتر المكتبي كنوع التطبيق.
تؤدي هذه العملية إلى إنشاء معرّف عميل، وفي بعض الحالات، سر عميل، يتم تضمينه في الرمز المصدر لتطبيقك. (في هذا السياق، من الواضح أنّه لا يتم التعامل مع سر العميل على أنّه سرّي).
يبدأ تسلسل التفويض عندما يعيد تطبيقك توجيه متصفّح إلى عنوان URL على Google، ويتضمّن عنوان URL معلمات طلب البحث التي تشير إلى نوع الوصول المطلوب. تتولى Google مصادقة المستخدم واختيار الجلسة وموافقة المستخدم. والنتيجة هي رمز تفويض يمكن للتطبيق استبداله برمز دخول. يجب أن يتحقّق التطبيق من صحة رمز الدخول قبل تضمينه في طلب بيانات من Google APIs. وعند انتهاء صلاحية الرمز المميّز، يكرّر التطبيق العملية.
يمكن لخادم الخلفية اختياريًا استبدال رمز التفويض برمز مميز لإعادة التحميل، وتخزينه في مكان آمن. بعد انتهاء صلاحية رمز الدخول، يستخدم خادم الواجهة الخلفية رمز إعادة التحميل للحصول على رمز جديد للتطبيق.
لمعرفة التفاصيل، يُرجى الاطّلاع على تفويض الوصول إلى بيانات مستخدمي Google لنظام التشغيل Android، والوصول إلى Google APIs في تطبيق iOS، وOAuth 2.0 للتطبيقات المتوافقة مع الكمبيوتر المكتبي.
تطبيقات من جهة العميل (JavaScript)
تتوافق نقطة نهاية Google OAuth 2.0 مع تطبيقات JavaScript التي تعمل في متصفّح.
يبدأ تسلسل التفويض عندما يعيد تطبيقك توجيه متصفّح إلى عنوان URL على Google، ويتضمّن عنوان URL معلمات طلب البحث التي تشير إلى نوع الوصول المطلوب. تتولى 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 APIs نيابةً عن حساب الخدمة، ولا يلزم الحصول على موافقة المستخدم. (في السيناريوهات التي لا تتضمّن حسابات خدمة، يطلب تطبيقك Google APIs نيابةً عن المستخدمين النهائيين، وقد يكون مطلوبًا الحصول على موافقة المستخدم في بعض الأحيان).
تتضمّن بيانات اعتماد حساب الخدمة، التي تحصل عليها من Google API Console، عنوان بريد إلكتروني فريدًا تم إنشاؤه ومعرِّف عميل وزوجًا واحدًا على الأقل من مفاتيح التشفير العامة/الخاصة. يمكنك استخدام معرّف العميل ومفتاح خاص واحد لإنشاء رمز JWT موقَّع وإنشاء طلب رمز مميّز للوصول بالتنسيق المناسب. بعد ذلك، يرسل تطبيقك طلب الرمز المميّز إلى خادم التفويض في Google OAuth 2.0، الذي يعرض رمز دخول. يستخدم التطبيق الرمز المميّز للوصول إلى Google API. وعند انتهاء صلاحية الرمز المميّز، يكرّر التطبيق العملية.
لمعرفة التفاصيل، يُرجى الاطّلاع على مستندات حساب الخدمة.
حجم الرمز المميّز
يمكن أن تختلف الرموز المميّزة في الحجم، حتى الحدود التالية:
إنّ رموز الدخول التي تعرضها واجهة برمجة التطبيقات Security Token Service API في Google Cloud منظَّمة بشكل مشابه لرموز الدخول في Google API OAuth 2.0، ولكنّها تختلف من حيث حدود حجم الرمز. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات.
تحتفظ 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"). وبما أنّ مدة الجلسة قد تكون محدودة جدًا (بين ساعة واحدة و24 ساعة)، يجب التعامل مع هذا السيناريو بسلاسة من خلال إعادة بدء جلسة مصادقة.
وبالمثل، يجب عدم استخدام بيانات اعتماد المستخدم أو تشجيع استخدامها في عمليات النشر من خادم إلى خادم. إذا تم نشر بيانات اعتماد المستخدم على خادم لمهام أو عمليات طويلة الأمد وطبّق العميل سياسات التحكّم في الجلسة على هؤلاء المستخدمين، سيتعذّر تشغيل تطبيق الخادم لأنّه لن تكون هناك طريقة لإعادة مصادقة المستخدم عند انتهاء مدة الجلسة.
لمزيد من المعلومات حول كيفية مساعدة عملائك في نشر هذه الميزة، يُرجى الرجوع إلى مقالة المساعدة هذه التي تركّز على المشرفين.
مكتبات العملاء
تتكامل مكتبات العملاء التالية مع أُطر العمل الشائعة، ما يسهّل تنفيذ بروتوكول OAuth 2.0. وستتم إضافة المزيد من الميزات إلى المكتبات بمرور الوقت.
- مكتبة Google Auth للغة Java
- مكتبة برامج Google API للغة Python
- مكتبة برامج Google API للغة Dart
- مكتبة برامج Google API للغة Go
- مكتبة عملاء Google API لنظام .NET
- مكتبة عملاء Google API للغة Ruby
- مكتبة عميل Google API للغة PHP
- مكتبة برامج Google API لـ JavaScript
- GTMAppAuth - مكتبة عميل OAuth لنظامَي التشغيل Mac وiOS