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

استخدام OAuth 2.0 للدخول إلى واجهات برمجة تطبيقات Google

تستخدم 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 Connect.

الخطوات الأساسية

تتبع جميع التطبيقات نمطًا أساسيًا عند الوصول إلى Google API باستخدام OAuth 2.0. بشكل عام، عليك اتّباع خمس خطوات:

1. احصل على بيانات اعتماد OAuth 2.0 من Google API Console.

انتقِل إلى Google API Console للحصول على بيانات اعتماد 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 API ذات الصلة. أوقِف أي ميزات في تطبيقك لا يمكنها العمل بدون الوصول إلى واجهة برمجة التطبيقات ذات الصلة.

قد لا يتطابق النطاق المضمَّن في طلبك مع النطاق المضمَّن في ردّك، حتى إذا منح المستخدم جميع النطاقات المطلوبة. يُرجى الرجوع إلى مستندات كل واجهة برمجة تطبيقات من 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 API. بعد انتهاء صلاحية رمز الدخول، يستخدم التطبيق الرمز المميز لإعادة التحميل للحصول على رمز جديد.

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

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

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

تتوافق نقطة نهاية Google OAuth 2.0 مع التطبيقات المثبّتة على أجهزة مثل أجهزة الكمبيوتر والأجهزة الجوّالة والأجهزة اللوحية. عند إنشاء معرّف عميل من خلال وحدة تحكّم Google API، حدِّد أنّ هذا تطبيق مثبَّت، ثم اختَر Android أو إضافة Chrome أو iOS أو تطبيق متوافق مع الكمبيوتر المكتبي كنوع التطبيق.

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

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

يمكن لخادم الخلفية اختياريًا استبدال رمز التفويض برمز مميز لإعادة التحميل، وتخزينه في مكان آمن. بعد انتهاء صلاحية رمز الدخول، يستخدم خادم الخلفية الرمز المميز لإعادة التحميل للحصول على رمز جديد للتطبيق.

لمعرفة التفاصيل، يُرجى الاطّلاع على تفويض الوصول إلى بيانات مستخدمي Google لأجهزة Android، والوصول إلى Google APIs في تطبيق iOS، وOAuth 2.0 للتطبيقات المتوافقة مع الكمبيوتر المكتبي.

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

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

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

يرسل تطبيق JS طلبًا للحصول على رمز مميّز إلى خادم التفويض في 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 API نيابةً عن المستخدمين النهائيين، وتكون موافقة المستخدم مطلوبة أحيانًا).

تتضمّن بيانات اعتماد حساب الخدمة التي تحصل عليها من Google API Console عنوان بريد إلكتروني فريدًا تم إنشاؤه ومعرّف عميل ومفتاح تشفير واحدًا على الأقل من مفاتيح التشفير العامة/الخاصة. يمكنك استخدام معرّف العميل ومفتاح خاص واحد لإنشاء رمز JWT موقَّع وإنشاء طلب رمز مميّز للوصول بالتنسيق المناسب. بعد ذلك، يرسل تطبيقك طلب الرمز المميّز إلى خادم تفويض Google OAuth 2.0، والذي يعرض رمز دخول. يستخدم التطبيق الرمز المميز للوصول إلى Google APIs. وعند انتهاء صلاحية الرمز المميّز، يكرّر التطبيق العملية.

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

حجم الرمز المميّز

يمكن أن تختلف الرموز المميّزة في الحجم، حتى الحدود التالية:

code رموز التفويض
256 بايت
contextual_token رموز الدخول
‫2048 بايت
restore_page الرموز المميزة لإعادة التحميل
512 بايت

تكون رموز الدخول التي تعرضها Security Token Service API في Google Cloud منظَّمة بشكل مشابه لرموز الدخول في Google API OAuth 2.0، ولكنّها تختلف في حدود حجم الرمز المميّز. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات.

تحتفظ Google بالحق في تغيير حجم الرمز المميّز ضمن هذه الحدود، ويجب أن يتيح تطبيقك استخدام أحجام الرموز المميّزة المتغيّرة وفقًا لذلك.

انتهاء صلاحية الرمز المميّز لإعادة التحميل

يجب كتابة الرمز لتوقُّع احتمال عدم عمل الرمز المميز لإعادة التحميل الذي تم منحه. قد يتوقف الرمز المميز لإعادة التحميل عن العمل لأحد الأسباب التالية:

shield_locked ألغى المستخدم إذن وصول تطبيقك.
لم يتم استخدام الرمز المميز لإعادة التحميل لمدة ستة أشهر.
غيّر المستخدم كلمات المرور ويحتوي الرمز المميز لإعادة التحميل على نطاقات Gmail.
تجاوز حساب المستخدم الحد الأقصى لعدد الرموز المميزة لإعادة التحميل (النشطة) التي تم منحها.
منح المستخدم إذن وصول مستند إلى الوقت إلى تطبيقك وانتهت صلاحية الإذن.
إذا ضبط المشرف أيًا من الخدمات المطلوبة في نطاقات تطبيقك على "محظورة" (الخطأ هو admin_policy_enforced).
cloud_lock بالنسبة إلى واجهات برمجة تطبيقات Google Cloud Platform، من المحتمل أن تكون مدة الجلسة التي حدّدها المشرف قد تم تجاوزها.

إذا كان لديك مشروع على 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 أسهل. ستتم إضافة المزيد من الميزات إلى المكتبات بمرور الوقت.