تستخدم 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.
الخطوات الأساسية
تتّبع جميع التطبيقات نمطًا أساسيًا عند الوصول إلى إحدى واجهات Google API باستخدام بروتوكول OAuth 2.0. على مستوى عالٍ، عليك اتّباع خمس خطوات:
1. احصل على بيانات اعتماد OAuth 2.0 من Google API Console.
انتقِل إلى Google API Console للحصول على بيانات اعتماد OAuth 2.0، مثل معرّف العميل وسر العميل المعروفَين لكلّ من Google وتطبيقك. تختلف مجموعة القيم حسب نوع التطبيق الذي تنشئه. على سبيل المثال، لا يتطلّب تطبيق JavaScript سرًا، ولكن يتطلّب تطبيق خادم الويب ذلك.
يجب إنشاء عميل OAuth مناسب للمنصة التي سيتم تشغيل تطبيقك عليها، على سبيل المثال:
- الرمز بالنسبة إلى تطبيقات الويب من جهة الخادم أو تطبيقات الويب المستندة إلى JavaScript، استخدِم نوع العميل "web". لا تستخدِم نوع العميل هذا لأي تطبيق آخر، مثل التطبيقات الأصلية أو تطبيقات الأجهزة الجوّالة.
- بالنسبة إلى تطبيقات Android، استخدِم نوع العميل "Android".
-
بالنسبة إلى تطبيقات iOS وmacOS، استخدِم
نوع العميل "iOS".
- بالنسبة إلى تطبيقات النظام الأساسي العام لـ Windows، استخدِم نوع العميل "النظام الأساسي العام لـ Windows".
- tv بالنسبة إلى الأجهزة التي تتطلّب إدخال بيانات محدودة، مثل أجهزة التلفزيون أو الأجهزة المضمّنة، استخدِم نوع العميل "أجهزة التلفزيون والأجهزة التي تتطلّب إدخال بيانات محدودة".
- المضيف بالنسبة إلى التفاعلات بين الخوادم، استخدِم حسابات الخدمة.
2. الحصول على رمز دخول من خادم التفويض في Google
قبل أن يتمكّن تطبيقك من الوصول إلى البيانات الخاصة باستخدام إحدى واجهات Google API، يجب أن يحصل على رمز مميّز للوصول يمنح إذن الوصول إلى واجهة برمجة التطبيقات هذه. يمكن أن يمنح رمز الدخول الواحد درجات متفاوتة من إذن الوصول إلى واجهات برمجة تطبيقات متعددة. تتحكّم مَعلمة متغيّرة باسم scope في مجموعة الموارد والعمليات التي يسمح بها رمز الدخول. أثناء طلب رمز الدخول، يرسل تطبيقك قيمة واحدة أو أكثر في المَعلمة scope.
تتوفّر عدّة طرق لتقديم هذا الطلب، وتختلف هذه الطرق حسب نوع التطبيق الذي تنشئه. على سبيل المثال، قد يطلب تطبيق JavaScript رمز دخول باستخدام عملية إعادة توجيه المتصفّح إلى Google، بينما يستخدم تطبيق مثبَّت على جهاز لا يتضمّن متصفّحًا طلبات خدمة الويب.
تتطلّب بعض الطلبات خطوة مصادقة يسجّل فيها المستخدم الدخول باستخدام حسابه على Google. بعد تسجيل الدخول، يُسأل المستخدم عمّا إذا كان على استعداد لمنح إذن واحد أو أكثر من الأذونات التي يطلبها تطبيقك. تُعرف هذه العملية باسم موافقة المستخدم.
إذا منح المستخدم إذنًا واحدًا على الأقل، يرسل خادم التفويض من Google إلى تطبيقك رمز دخول (أو رمز تفويض يمكن لتطبيقك استخدامه للحصول على رمز دخول) وقائمة بنطاقات الوصول التي يمنحها هذا الرمز. إذا لم يمنح المستخدم الإذن، سيعرض الخادم رسالة خطأ.
من أفضل الممارسات عمومًا طلب النطاقات بشكل تدريجي، عند الحاجة إلى إذن الوصول، بدلاً من طلبها مسبقًا. على سبيل المثال، يجب ألا يطلب تطبيق يريد إتاحة حفظ حدث في تقويم الوصول إلى "تقويم Google" إلا بعد أن ينقر المستخدم على الزر "إضافة إلى التقويم"، راجِع تفويض الوصول بشكل تدريجي.
3- فحص نطاقات الوصول التي منحها المستخدم
قارِن النطاقات المضمَّنة في استجابة الرمز المميز للوصول بالنطاقات المطلوبة للوصول إلى ميزات تطبيقك ووظائفه التي تعتمد على الوصول إلى إحدى واجهات Google ذات الصلة. إيقاف أي ميزات في تطبيقك لا يمكنها العمل بدون الوصول إلى واجهة برمجة التطبيقات ذات الصلة
قد لا يتطابق النطاق المضمّن في طلبك مع النطاق المضمّن في ردّك، حتى إذا منح المستخدم جميع النطاقات المطلوبة. راجِع المستندات الخاصة بكل واجهة من واجهات Google API لمعرفة النطاقات المطلوبة للوصول إليها. قد يربط أحد واجهات برمجة التطبيقات قيمًا متعددة لسلسلة النطاق بنطاق وصول واحد، مع عرض سلسلة النطاق نفسها لجميع القيم المسموح بها في الطلب.
مثال: قد تعرض واجهة Google People API نطاق https://www.googleapis.com/auth/contacts عندما يطلب تطبيق من المستخدم منح إذن بنطاق https://www.google.com/m8/feeds/، ويتطلّب أسلوب people.updateContact في واجهة Google People API نطاقًا ممنوحًا بقيمة https://www.googleapis.com/auth/contacts.
4. إرسال رمز الدخول إلى واجهة برمجة تطبيقات
بعد أن يحصل التطبيق على رمز مميز للوصول، يرسل الرمز إلى إحدى واجهات برمجة التطبيقات من Google في عنوان طلب تفويض HTTP. يمكن إرسال الرموز المميزة كمعلَمات سلسلة طلب البحث في معرّف الموارد المنتظم (URI)، ولكن لا ننصح بذلك، لأنّ معلَمات معرّف الموارد المنتظم يمكن أن تنتهي في ملفات السجلّ غير الآمنة تمامًا. بالإضافة إلى ذلك، من الممارسات الجيدة في REST تجنُّب إنشاء أسماء مَعلمات غير ضرورية لمعرّف الموارد المنتظم (URI).
تكون رموز الدخول المميزة صالحة فقط لمجموعة العمليات والموارد الموضّحة في
scope لطلب الرمز المميز. على سبيل المثال، إذا تم إصدار رمز مميّز للوصول إلى واجهة برمجة التطبيقات الخاصة بـ "تقويم Google"، لن يمنح هذا الرمز إذن الوصول إلى واجهة برمجة التطبيقات الخاصة بـ "جهات اتصال Google". ومع ذلك، يمكنك إرسال رمز الدخول هذا إلى واجهة برمجة التطبيقات الخاصة بـ "تقويم Google" عدة مرات لإجراء عمليات مشابهة.
5- أعِد تحميل رمز الدخول المميز، إذا لزم الأمر.
تكون مدة صلاحية رموز الدخول محدودة. إذا كان تطبيقك يحتاج إلى الوصول إلى إحدى واجهات برمجة التطبيقات من Google بعد انتهاء صلاحية رمز الدخول، يمكنه الحصول على رمز مميز لإعادة التحميل. يسمح رمز التحديث لتطبيقك بالحصول على رموز دخول جديدة.
السيناريوهات
تطبيقات خادم الويب
تتيح نقطة نهاية 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 أو Universal Windows Platform (UWP) أو تطبيق كمبيوتر مكتبي كنوع التطبيق.
تؤدي هذه العملية إلى إنشاء معرّف عميل، وفي بعض الحالات، سر عميل، ويتم تضمينهما في الشفرة المصدر لتطبيقك. (في هذا السياق، من الواضح أنّ سر العميل لا يُعامل على أنّه سر).
تبدأ سلسلة طلب الإذن عندما يعيد تطبيقك توجيه المتصفّح إلى عنوان URL تابع لـ Google، ويتضمّن عنوان URL مَعلمات طلب البحث التي تشير إلى نوع الوصول المطلوب. تتولّى Google عملية مصادقة المستخدم واختيار الجلسة والحصول على موافقة المستخدم. والنتيجة هي رمز تفويض يمكن للتطبيق استبداله برمز دخول ورمز مميز لإعادة التحميل.
يجب أن يخزّن التطبيق الرمز المميز لإعادة التحميل لاستخدامه في المستقبل، وأن يستخدم رمز الدخول للوصول إلى إحدى واجهات Google API. وبعد انتهاء صلاحية رمز الدخول، يستخدم التطبيق رمز إعادة التحميل للحصول على رمز جديد.
لمعرفة التفاصيل، يُرجى الاطّلاع على استخدام 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 API، مثل Prediction API وGoogle Cloud Storage، أن تعمل نيابةً عن تطبيقك بدون الوصول إلى معلومات المستخدم. في هذه الحالات، يجب أن يثبت تطبيقك هويته لواجهة برمجة التطبيقات، ولكن لا يلزم الحصول على موافقة المستخدم. وبالمثل، في سيناريوهات المؤسسات، يمكن لتطبيقك طلب إذن وصول مفوَّض إلى بعض الموارد.
لهذه الأنواع من التفاعلات بين الخادم والخادم، تحتاج إلى حساب خدمة، وهو حساب يخص تطبيقك بدلاً من مستخدم نهائي فردي. يطلب تطبيقك بيانات من واجهات برمجة تطبيقات Google بالنيابة عن حساب الخدمة، ولا يلزم الحصول على موافقة المستخدم. (في سيناريوهات غير حسابات الخدمة، يطلب تطبيقك من واجهات برمجة التطبيقات من Google تنفيذ إجراءات نيابةً عن المستخدمين النهائيين، وفي بعض الأحيان، يجب الحصول على موافقة المستخدمين.)
تتضمّن بيانات اعتماد حساب الخدمة، التي تحصل عليها من Google API Console، عنوان بريد إلكتروني تم إنشاؤه وهو فريد، ومعرّف عميل، وزوج مفتاح عام/خاص واحد على الأقل. يمكنك استخدام معرّف العميل ومفتاح خاص واحد لإنشاء رمز JWT موقَّع وإنشاء طلب رمز مميّز للوصول بالتنسيق المناسب. بعد ذلك، يرسل تطبيقك طلب الرمز المميز إلى خادم المصادقة في Google OAuth 2.0، الذي يعرض رمز دخول. يستخدم التطبيق الرمز المميز للوصول إلى إحدى واجهات Google API. وعند انتهاء صلاحية الرمز المميّز، يعيد التطبيق العملية.
لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات حساب الخدمة.
حجم الرمز المميز
يمكن أن تختلف الرموز المميزة في الحجم، وذلك حتى الحدود التالية:
تتشابه رموز الدخول التي تعرضها Security Token Service API من Google Cloud في بنيتها مع رموز الدخول الخاصة ببروتوكول OAuth 2.0 لواجهات برمجة التطبيقات من Google، ولكنّها تختلف في الحدود القصوى المسموح بها لحجم الرمز المميّز. لمعرفة التفاصيل، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات.
تحتفظ Google بالحق في تغيير حجم الرمز المميز ضمن هذه الحدود، ويجب أن يدعم تطبيقك أحجام الرموز المميزة المتغيرة وفقًا لذلك.
انتهاء صلاحية الرمز المميز لإعادة التحميل
يجب كتابة الرمز البرمجي لتوقُّع احتمال عدم عمل رمز التحديث المميز الذي تم منحه. قد يتوقّف رمز التحديث عن العمل لأحد الأسباب التالية:
يتم إصدار رمز مميّز لإعادة التحميل ينتهي بعد 7 أيام لمشروع على Google Cloud Platform تم ضبط شاشة طلب الموافقة على OAuth فيه لنوع مستخدم خارجي وحالة نشر "قيد الاختبار"، ما لم تكن نطاقات 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) وأي تطبيق OAuth تابع لجهة خارجية يتطلّب نطاق Cloud Platform. إذا كان المستخدم يخضع لسياسة تحكّم في الجلسة، ستؤدي انتهاء مدة الجلسة إلى حدوث خطأ في طلبات البيانات من واجهة برمجة التطبيقات، على غرار ما يحدث عند إلغاء الرمز المميز لإعادة التحميل، أي سيتعذّر تنفيذ الطلب مع ظهور نوع الخطأ invalid_grant. ويمكن استخدام الحقل error_subtype للتمييز بين الرمز المميز الملغى والخطأ الناتج عن سياسة تحكّم في الجلسة (مثل "error_subtype": "invalid_rapt"). وبما أنّ مدة الجلسات قد تكون محدودة جدًا (بين ساعة واحدة و24 ساعة)، يجب التعامل مع هذا السيناريو بشكل سليم من خلال إعادة تشغيل جلسة مصادقة.
وبالمثل، يجب عدم استخدام بيانات اعتماد المستخدمين أو التشجيع على استخدامها في عمليات النشر من خادم إلى خادم. إذا تم نشر بيانات اعتماد المستخدم على خادم لتنفيذ مهام أو عمليات طويلة الأمد، وطبّق أحد العملاء سياسات التحكّم في الجلسة على هؤلاء المستخدمين، سيتعذّر تشغيل تطبيق الخادم لأنّه لن يكون هناك طريقة لإعادة مصادقة المستخدم عند انتهاء مدة الجلسة.
للمزيد من المعلومات حول كيفية مساعدة عملائك في نشر هذه الميزة، يُرجى الرجوع إلى مقالة المساعدة المخصّصة للمشرفين.
مكتبات العملاء
تتكامل مكتبات البرامج التالية مع أُطر العمل الشائعة، ما يسهّل تنفيذ بروتوكول OAuth 2.0. سنضيف المزيد من الميزات إلى المكتبات بمرور الوقت.
- مكتبة برامج Google API Client Library للغة Java
- Google API Client Library for Python
- Google API Client Library for Go
- Google API Client Library for .NET
- مكتبة برامج Google API للغة Ruby
- مكتبة برامج Google API للغة PHP
- Google API Client Library for JavaScript
- GTMAppAuth - مكتبة برامج عميل OAuth لنظام التشغيل Mac وiOS