تستخدم 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 API، يجب أن يحصل على رمز دخول يمنحه إذن الوصول إلى واجهة برمجة التطبيقات هذه. ويمكن أن يمنح رمز الدخول الواحد درجات متفاوتة
من الوصول إلى واجهات برمجة تطبيقات متعددة. تتحكّم مَعلمة متغيّرة تُسمّى scope في مجموعة
الموارد والعمليات التي يسمح بها رمز الدخول. أثناء طلب رمز الدخول، يرسل تطبيقك قيمة واحدة أو أكثر في المَعلمة scope.
هناك عدة طرق لتقديم هذا الطلب، وتختلف حسب نوع التطبيق الذي تنشئه. على سبيل المثال، قد يطلب تطبيق JavaScript رمز دخول باستخدام إعادة توجيه المتصفّح إلى Google، بينما يستخدم تطبيق مثبّت على جهاز لا يحتوي على متصفّح طلبات خدمة الويب. لمزيد من المعلومات حول كيفية تقديم الطلب، يُرجى الاطّلاع على Scenarios وأدلة الاستخدام المفصّلة لكل نوع من أنواع التطبيقات.
تتطلّب بعض الطلبات خطوة مصادقة يسجّل فيها المستخدم الدخول باستخدام حسابه على Google. After logging in, the user is asked whether they are willing to grant one or more permissions that your application is requesting. تُعرف هذه العملية باسم موافقة المستخدم.
إذا منح المستخدم إذنًا واحدًا على الأقل، يرسل خادم التفويض في 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 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 APIs. بعد انتهاء صلاحية رمز الدخول، يستخدم التطبيق الرمز المميز لإعادة التحميل للحصول على رمز جديد.
لمعرفة التفاصيل، يُرجى الاطّلاع على استخدام 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. وعند انتهاء صلاحية الرمز المميّز، يكرّر التطبيق العملية.
لمعرفة التفاصيل، يُرجى الاطّلاع على استخدام 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 API نيابةً عن المستخدمين النهائيين، وقد يكون مطلوبًا في بعض الأحيان الحصول على موافقة المستخدم).
تتضمّن بيانات اعتماد حساب الخدمة، التي تحصل عليها من 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