تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

للبدء، عليك الحصول على بيانات اعتماد عميل OAuth 2.0 من . بعد ذلك، يطلب تطبيق العميل رمز دخول من خادم 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 من .

يُرجى الانتقال إلى للحصول على بيانات اعتماد OAuth 2.0، مثل معرِّف العميل وسر العميل اللذَين يعرفهما كل من Google وتطبيقك. تختلف مجموعة القيم حسب نوع التطبيق الذي تُنشئه. على سبيل المثال، لا يتطلّب تطبيق JavaScript سرًا، ولكن يتطلّب تطبيق خادم الويب سرًا.

يجب إنشاء عميل OAuth مناسب للنظام الأساسي الذي سيتم تشغيل تطبيقك عليه، على سبيل المثال:

بالنسبة إلى التطبيقات من جهة الخادم أو تطبيقات الويب المستندة إلى JavaScript، استخدِم نوع العميل "الويب". لا تستخدِم نوع العميل هذا لأي تطبيق آخر، مثل التطبيقات المتوافقة مع الأجهزة الجوّالة أو التطبيقات المضمّنة.
بالنسبة إلى تطبيقات Android، استخدِم نوع العميل "Android".
بالنسبة إلى تطبيقات iOS وmacOS، استخدِم نوع العميل "iOS".
بالنسبة إلى تطبيقات النظام الأساسي العام لـ Windows، استخدِم نوع العميل "النظام الأساسي العام لـ Windows".
بالنسبة إلى أجهزة التحكّم المحدود بالإدخال، مثل أجهزة التلفزيون أو الأجهزة المضمّنة، استخدِم نوع العميل "أجهزة التلفزيون والأجهزة التي تتطلّب إدخال بيانات محدودة".
بالنسبة إلى التفاعلات من خادم إلى خادم، استخدِم حسابات الخدمة.

2. الحصول على رمز دخول من خادم تفويض Google

قبل أن يتمكّن تطبيقك من الوصول إلى البيانات الخاصة باستخدام Google API، يجب أن يحصل على رمز مميّز للوصول يمنح إذن الوصول إلى واجهة برمجة التطبيقات هذه. يمكن أن يمنح رمز دخول واجهة برمجة تطبيقات واحد درجات مختلفة من الوصول إلى واجهات برمجة تطبيقات متعددة. تتحكّم مَعلمة متغيّرة تُسمى scope في مجموعة الموارد والعمليات التي يسمح بها رمز الوصول. أثناء طلب الحصول على رمز الوصول، يُرسِل تطبيقك قيمة واحدة أو أكثر في المَعلمة scope.

هناك عدة طرق لتقديم هذا الطلب، وتختلف هذه الطرق حسب نوع التطبيق الذي تنشئه. على سبيل المثال، قد يطلب تطبيق JavaScript رمز أمان وصول باستخدام عملية إعادة توجيه المتصفّح إلى Google، في حين يستخدم تطبيق مثبّت على جهاز لا يحتوي على متصفّح طلبات خدمة الويب.

تتطلّب بعض الطلبات خطوة مصادقة يسجّل فيها المستخدم الدخول باستخدام حسابه على 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 في رأس طلب التفويض باستخدام بروتوكول HTTP. من الممكن إرسال الرموز المميّزة كمَعلمات لسلاسل طلبات البحث الخاصة بمعرّفات الموارد المنتظّمة، ولكن لا ننصح بذلك، لأنّ مَعلمات معرّفات الموارد المنتظّمة يمكن أن تنتهي في ملفات سجلّ غير آمنة تمامًا. من الممارسات الجيدة في REST أيضًا عدم إنشاء أسماء مَعلمات معرّف الموارد المنتظم (URI) غير الضرورية.

لا تكون الرموز المميّزة للوصول صالحة إلا لمجموعة العمليات والموارد الموضّحة في scope من طلب الرمز المميّز. على سبيل المثال، إذا تم إصدار رمز مميّز للوصول إلى واجهة برمجة التطبيقات Google Calendar API، لن يمنح هذا الرمز إمكانية الوصول إلى واجهة برمجة التطبيقات Google Contacts API. ومع ذلك، يمكنك إرسال رمز الوصول هذا إلى Google Calendar API عدة مرات لإجراء عمليات مشابهة.

5- أعِد تحميل رمز الوصول المميّز، إذا لزم الأمر.

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

السيناريوهات

تطبيقات خادم الويب

تتوافق نقطة نهاية Google OAuth 2.0 مع تطبيقات خادم الويب التي تستخدم لغات و أُطر عمل مثل PHP وJava وGo وPython وRuby وASP.NET.

يبدأ تسلسل التفويض عندما يعيد تطبيقك توجيه المتصفّح إلى عنوان URL في Google ، ويتضمن عنوان URL مَعلمات طلب بحث تشير إلى نوع الوصول المطلوب. تتولى Google مصادقة المستخدم واختيار الجلسة والحصول على موافقة المستخدم. والنتيجة هي رمز تفويض يمكن للتطبيق استبداله برمز دخول ورمز تحديث.

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

يُرسِل تطبيقك طلبًا للحصول على رمز مميّز إلى "خادم مصادقة Google"، ويتلقّى رمز مصادقة، ويتبادل الرمز للحصول على رمز مميّز، ويستخدم الرمز المميّز لاستدعاء نقطة نهاية واجهة برمجة تطبيقات Google.

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

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

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

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

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

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

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

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

يُرسِل تطبيق JavaScript طلب رمز مميّز إلى خادم تفويض Google، ويتلقّى الرمز المميّز ويُجري عملية التحقّق منه ويستخدمه لاستدعاء نقطة نهاية لواجهة برمجة تطبيقات Google.

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

التطبيقات على الأجهزة التي تتطلّب إدخال بيانات محدودة

تتوافق نقطة نهاية Google OAuth 2.0 مع التطبيقات التي تعمل على أجهزة ذات إدخال محدود، مثل أجهزة تحكّم الألعاب وكاميرات الفيديو والطابعات.

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

يحصل المستخدم على عنوان URL والرمز من الجهاز، ثم ينتقل إلى جهاز أو كمبيوتر منفصل مزوّد بإمكانات إدخال أكثر شمولاً. يشغِّل المستخدم متصفّحًا وينتقل إلى عنوان URL المحدّد، ثم يسجّل الدخول ويُدخِل الرمز.

وفي الوقت نفسه، يُجري التطبيق استطلاعًا لعنوان URL في Google على فترات زمنية محدّدة. بعد أن يمنح المستخدم موافقته على الوصول، يحتوي الردّ من خادم Google على رمز دخول ورمز إعادة تحميل. يجب أن يخزِّن التطبيق الرمز المميّز لإعادة التحميل لاستخدامه في المستقبل، وأن يستخدم رمز الوصول للوصول إلى واجهة برمجة تطبيقات Google. بعد انتهاء صلاحية رمز الوصول، يستخدم التطبيق رمز إعادة التحميل للحصول على رمز جديد.

سجّل المستخدم الدخول على جهاز منفصل مزوّد بمتصفّح.

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

حسابات الخدمة

يمكن لواجهات برمجة تطبيقات Google، مثل Prediction API وGoogle Cloud Storage، التصرف نيابةً عن تطبيقك بدون الوصول إلى معلومات المستخدم. وفي هذه الحالات، يحتاج تطبيقك إلى إثبات هويته لواجهة برمجة التطبيقات، ولكن لا يلزم الحصول على موافقة المستخدم. وبالمثل، في حالات المؤسسات، يمكن لتطبيقك طلب إذن وصول مفوَّض إلى بعض الموارد.

بالنسبة إلى هذه الأنواع من التفاعلات من خادم إلى خادم، ستحتاج إلى حساب خدمة، وهو حساب ينتمي إلى تطبيقك بدلاً من مستخدم فردي. يُطلِب تطبيقك واجهات برمجة تطبيقات Google بالنيابة عن حساب الخدمة، ولا يُشترَط الحصول على موافقة المستخدم. (في سيناريوهات استخدام حسابات غير حسابات الخدمة، يطلب تطبيقك بيانات من واجهات برمجة تطبيقات Google نيابةً عن المستخدمين النهائيين، وتكون موافقة المستخدم مطلوبة في بعض الأحيان).

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

يستخدم تطبيق الخادم تنسيق JWT لطلب رمز مميّز من "خادم مصادقة Google"، ثم يستخدم الرمز المميّز للاتّصال بنقطة نهاية واجهة برمجة تطبيقات Google. لا يشارك أي
مستخدِم نهائي في العملية.

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

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

يمكن أن يختلف حجم الرموز إلى الحدّ الأقصى التالي:

رموز التفويض: 256 بايت
رموز الوصول: 2048 بايت
الرموز المميّزة لإعادة التحميل: 512 بايت

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

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

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

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

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

إذا كان مشروع 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

قد يطلب مشرفي المؤسسات على Google Cloud Platform إعادة مصادقة المستخدمين بشكل متكرّر أثناء وصولهم إلى موارد Google Cloud باستخدام ميزة التحكّم في جلسة Google Cloud. تؤثر هذه السياسة في الوصول إلى Google Cloud Console وGoogle Cloud SDK (المعروفة أيضًا باسم gcloud CLI) وأي تطبيق OAuth تابع لجهة خارجية يتطلب نطاق Cloud Platform. إذا كان أحد المستخدِمين لديه سياسة التحكّم في الجلسة، عند انتهاء مدة الجلسة، ستظهر أخطاء في طلبات البيانات من واجهة برمجة التطبيقات، تمامًا كما لو تم إبطال رمز إعادة التحميل. ستتعذّر إتمام الطلب بظهور نوع الخطأ invalid_grant. يمكن استخدام الحقل error_subtype للتمييز بين رمز مُلغى وخطأ بسبب سياسة التحكّم في الجلسة (على سبيل المثال، "error_subtype": "invalid_rapt"). وبما أنّ مدد الجلسات يمكن أن تكون محدودة جدًا (من ساعة إلى 24 ساعة)، يجب التعامل مع هذا السيناريو بشكل سلس من خلال إعادة تشغيل جلسة المصادقة.

وبالمثل، يجب عدم استخدام بيانات اعتماد المستخدمين أو التشجيع على استخدامها لعملية النشر من خادم إلى آخر. في حال نشر بيانات اعتماد المستخدمين على خادم لوظائف أو عمليات تستغرق وقتًا طويلاً وطبَّق العميل سياسات التحكّم في الجلسات على هؤلاء المستخدمين، لن يعمل تطبيق الخادم لأنّه لن تكون هناك طريقة لإعادة مصادقة المستخدم عند انتهاء صلاحية مدة الجلسة.

لمزيد من المعلومات حول كيفية مساعدة عملائك على نشر هذه الميزة، يمكنك الرجوع إلى مقالة المساعدة التي تركّز على المشرفين.

مكتبات العملاء

تتكامل مكتبات العملاء التالية مع إطارات العمل الشائعة، ما يسهّل تنفيذ بروتوكول OAuth 2.0. وستتم إضافة المزيد من الميزات إلى المكتبات بمرور الوقت.