تستخدم واجهات Google APIs بروتوكول OAuth 2.0 للمصادقة والتفويض. تتيح Google سيناريوهات OAuth 2.0 الشائعة، مثل تلك الخاصة بتطبيقات خادم الويب والتطبيقات من جهة العميل والتطبيقات المثبَّتة وتطبيقات الأجهزة ذات الإدخال المحدود.
للبدء، احصل على بيانات اعتماد عميل OAuth 2.0 من وحدة تحكّم Google API. بعد ذلك، يطلب تطبيق العميل رمز دخول من خادم التفويض في 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 للحصول على بيانات اعتماد OAuth 2.0، مثل معرِّف العميل وسر العميل، المعروفة لكلّ من Google وتطبيقك. تختلف مجموعة القيم بناءً على نوع التطبيق الذي تقوم بإنشائه. على سبيل المثال، لا يتطلب تطبيق JavaScript رمزًا سريًا، ولكن يتطلب تطبيق خادم الويب ذلك.
يجب إنشاء عميل OAuth مناسب للمنصة التي سيتم تشغيل تطبيقك عليها، على سبيل المثال:
2. الحصول على رمز دخول من خادم التفويض في Google
قبل أن يتمكّن تطبيقك من الوصول إلى البيانات الخاصة باستخدام Google APIs، يجب أن يحصل على رمز الدخول الذي يمنحه إذن الوصول إلى واجهة برمجة التطبيقات هذه. يمكن لرمز دخول واحد منح درجات متفاوتة
من الوصول إلى واجهات برمجة تطبيقات متعددة. تتحكّم مَعلمة متغيّرة تُسمّى scope في مجموعة الموارد والعمليات التي يسمح بها رمز الدخول. خلال طلب رمز الدخول، يرسل تطبيقك قيمة واحدة أو أكثر في المَعلمة scope.
هناك عدة طرق لتقديم هذا الطلب، وتختلف حسب نوع التطبيق الذي تنشئه. على سبيل المثال، قد يطلب تطبيق JavaScript رمز الدخول باستخدام إعادة توجيه المتصفّح إلى Google، بينما يستخدم تطبيق مثبّت على جهاز لا يتضمّن متصفّحًا طلبات خدمة الويب. لمزيد من المعلومات حول كيفية تقديم الطلب، يُرجى الاطّلاع على Scenarios وأدلة الاستخدام التفصيلية لكل نوع من أنواع التطبيقات.
تتطلّب بعض الطلبات خطوة مصادقة يسجّل فيها المستخدم الدخول باستخدام حسابه على 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 في عنوان طلب تفويض HTTP. يمكن إرسال الرموز المميّزة كمَعلمات لسلسلة طلبات البحث في معرّف الموارد المنتظم (URI)، ولكن لا ننصح بذلك لأنّ مَعلمات معرّف الموارد المنتظم (URI) قد ينتهي بها الأمر في ملفات السجلّات غير الآمنة تمامًا. من الممارسات الجيدة أيضًا في REST تجنُّب إنشاء أسماء معلَمات URI غير ضرورية.
تكون رموز الدخول صالحة فقط لمجموعة العمليات والموارد الموضحة في scope لطلب الرمز المميز. على سبيل المثال، إذا تم إصدار رمز مميّز للوصول إلى تقويم Google API، لن يمنح هذا الرمز إذن الوصول إلى جهات اتصال Google API. ومع ذلك، يمكنك إرسال رمز الدخول هذا إلى واجهة برمجة تطبيقات تقويم Google
عدة مرات لإجراء عمليات مماثلة.
5- أعِد تحميل رمز الدخول، إذا لزم الأمر.
تكون مدة صلاحية رموز الدخول محدودة. إذا كان تطبيقك يحتاج إلى الوصول إلى Google APIs بعد انتهاء صلاحية رمز الدخول واحد، يمكنه الحصول على الرمز المميز لإعادة التحميل. يسمح الرمز المميز لإعادة التحميل لتطبيقك بالحصول على رموز دخول جديدة.
السيناريوهات
توضّح هذه السيناريوهات كيفية استخدام OAuth 2.0 لطلب رموز التفويض والحصول على رموز الدخول وإعادة التحميل لأنواع مختلفة من التطبيقات.
تطبيقات خادم الويب
تتيح نقطة نهاية Google OAuth 2.0 استخدام تطبيقات خادم الويب التي تستخدم لغات وأُطر عمل مثل PHP وJava وGo وPython وRuby وASP.NET.
يبدأ تسلسل التفويض عندما يعيد تطبيقك توجيه متصفّح إلى عنوان URL على Google، ويتضمّن عنوان URL معلمات طلب البحث التي تشير إلى نوع الوصول المطلوب. تتولى Google معالجة مصادقة المستخدم واختيار الجلسة وموافقة المستخدم. والنتيجة هي رمز تفويض يمكن للتطبيق استبداله برمز دخول ورمز مميّز لإعادة التحميل.
يجب أن يخزّن التطبيق الرمز المميز لإعادة التحميل لاستخدامه في المستقبل، وأن يستخدم رمز الدخول للوصول إلى واجهة برمجة تطبيقات Google. بعد انتهاء صلاحية رمز الدخول، يستخدم التطبيق الرمز المميز لإعادة التحميل للحصول على رمز جديد.
لمعرفة التفاصيل، يُرجى الاطّلاع على استخدام OAuth 2.0 لتطبيقات خادم الويب.
التطبيقات المثبتة
تتوافق نقطة نهاية Google OAuth 2.0 مع التطبيقات المثبّتة على أجهزة مثل أجهزة الكمبيوتر والأجهزة الجوّالة والأجهزة اللوحية. عند إنشاء معرّف عميل من خلال وحدة تحكّم Google API، حدِّد أنّ هذا التطبيق مثبَّت، ثم اختَر Android أو إضافة Chrome أو iOS أو تطبيق متوافق مع الكمبيوتر المكتبي كنوع التطبيق.
تؤدي هذه العملية إلى إنشاء معرّف عميل، وفي بعض الحالات، سر عميل، يتم تضمينهما في الرمز المصدر لتطبيقك. (في هذا السياق، من الواضح أنّه لا يتم التعامل مع سر العميل على أنّه سرّي).
يبدأ تسلسل التفويض عندما يعيد تطبيقك توجيه متصفّح إلى عنوان URL على Google، ويتضمّن عنوان URL معلمات طلب البحث التي تشير إلى نوع الوصول المطلوب. تتولى Google معالجة مصادقة المستخدم واختيار الجلسة وموافقة المستخدم. والنتيجة هي رمز تفويض يمكن للتطبيق استبداله برمز دخول.
يجب أن يتحقّق التطبيق من صحة رمز الدخول قبل تضمينه في طلب بيانات من واجهة برمجة تطبيقات Google. وعند انتهاء صلاحية الرمز المميّز، يكرّر التطبيق العملية.
يمكن لخادم الخلفية اختياريًا استبدال رمز التفويض برمز مميز لإعادة التحميل، وتخزينه في مكان آمن. بعد انتهاء صلاحية الرمز المميز للوصول، يستخدم خادم الخلفية الرمز المميز لإعادة التحميل للحصول على رمز جديد للتطبيق.
لمعرفة التفاصيل، يُرجى الاطّلاع على تفويض الوصول إلى بيانات مستخدمي 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 APIs. وبعد انتهاء صلاحية رمز الدخول، يستخدم التطبيق الرمز المميز لإعادة التحميل للحصول على رمز جديد.
لمعرفة التفاصيل، يُرجى الاطّلاع على استخدام OAuth 2.0 للأجهزة.
حسابات الخدمة
يمكن لواجهات برمجة تطبيقات Google، مثل Prediction API وGoogle Cloud Storage، العمل نيابةً عن تطبيقك بدون الوصول إلى معلومات المستخدمين. في هذه الحالات، يحتاج تطبيقك إلى إثبات هويته لواجهة برمجة التطبيقات، ولكن لا يلزم الحصول على موافقة المستخدم. وبالمثل، في سيناريوهات المؤسسات، يمكن لتطبيقك طلب الوصول المفوَّض إلى بعض الموارد.
بالنسبة إلى هذه الأنواع من التفاعلات بين الخوادم، تحتاج إلى حساب خدمة، وهو حساب ينتمي إلى تطبيقك بدلاً من مستخدم نهائي فردي. يستدعي تطبيقك واجهات Google API نيابةً عن حساب الخدمة، ولا يلزم الحصول على موافقة المستخدم. (في السيناريوهات التي لا تتضمّن حسابات خدمة، يطلب تطبيقك واجهات Google API نيابةً عن المستخدمين النهائيين، وتكون موافقة المستخدم مطلوبة في بعض الأحيان).
تتضمّن بيانات اعتماد حساب الخدمة التي تحصل عليها من Google API Console عنوان بريد إلكتروني فريدًا تم إنشاؤه ومعرّف عميل ومفتاح تشفير واحدًا على الأقل من مفاتيح التشفير العامة/الخاصة. يمكنك استخدام معرّف العميل ومفتاح خاص واحد لإنشاء رمز JWT موقَّع وإنشاء طلب رمز مميّز للوصول بالتنسيق المناسب. بعد ذلك، يرسل تطبيقك طلب الرمز المميّز إلى خادم التفويض في Google OAuth 2.0، والذي يعرض رمز دخول. يستخدم التطبيق الرمز المميز للوصول إلى Google APIs. وعند انتهاء صلاحية الرمز المميّز، يكرّر التطبيق العملية.
لمعرفة التفاصيل، يُرجى الاطّلاع على مستندات حساب الخدمة.
حجم الرمز المميّز
يمكن أن تختلف الرموز المميّزة في الحجم، حتى الحدود التالية:
إنّ رموز الدخول التي تعرضها Security Token Service API من Google Cloud تكون منظَّمة بشكل مشابه لرموز الدخول في Google API OAuth 2.0، ولكنّها تختلف من حيث حدود حجم الرموز. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات.
تحتفظ Google بالحق في تغيير حجم الرمز المميّز ضمن هذه الحدود، ويجب أن يتيح تطبيقك أحجام الرموز المميّزة المتغيّرة وفقًا لذلك.
انتهاء صلاحية الرمز المميّز لإعادة التحميل
يجب كتابة الرمز لتوقّع احتمال عدم عمل الرمز المميز لإعادة التحميل الذي تم منحه. قد يتوقف الرمز المميز لإعادة التحميل عن العمل لأحد الأسباب التالية:
بالنسبة إلى مشاريع Google Cloud Platform التي تم إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth لها لنوع مستخدم خارجي وحالة نشر "قيد الاختبار"، يتم إصدار رمز مميز لإعادة التحميل تنتهي صلاحيته بعد 7 أيام، ما لم تكن نطاقات OAuth الوحيدة المطلوبة هي مجموعة فرعية من الاسم وعنوان البريد الإلكتروني والملف الشخصي للمستخدم (من خلال نطاقات userinfo.email, userinfo.profile, openid أو ما يعادلها من اتصال OpenID).
هناك حاليًا حدّ أقصى يبلغ 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
