تلتزم Google بتعزيز المساواة العرقية في المجتمعات السوداء. أنظر كيف.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

استخدام OAuth 2.0 للوصول إلى Google APIs

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

تقدم هذه الصفحة نظرة عامة على سيناريوهات مصادقة 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 سرًا ، ولكن يتطلب تطبيق خادم الويب ذلك.

2. احصل على رمز وصول من خادم مصادقة Google.

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

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

تتطلب بعض الطلبات خطوة مصادقة حيث يقوم المستخدم بتسجيل الدخول باستخدام حساب 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. إرسال رمز الوصول إلى API.

بعد حصول التطبيق على رمز وصول ، فإنه يرسل الرمز المميز إلى Google API في عنوان طلب تفويض HTTP . من الممكن إرسال الرموز المميزة كمعلمات لسلسلة استعلام URI ، لكننا لا نوصي بذلك ، لأن معلمات URI يمكن أن تنتهي في ملفات السجل غير الآمنة تمامًا. أيضًا ، من الجيد ممارسة REST لتجنب إنشاء أسماء معلمات URI غير ضرورية. لاحظ أنه سيتم إيقاف دعم سلسلة الاستعلام في الأول من يونيو 2021.

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

5. قم بتحديث رمز الوصول ، إذا لزم الأمر.

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

سيناريوهات

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

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

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

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

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

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

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

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

تدعم نقطة نهاية Google OAuth 2.0 تطبيقات جافا سكريبت التي تعمل في المتصفح.

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

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

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

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

يستخدم تطبيق الخادم الخاص بك JWT لطلب رمز مميز من Google Authorization Server ، ثم يستخدم الرمز المميز لاستدعاء نقطة نهاية Google API. لا يوجد مستخدم نهائي متورط.

للحصول على التفاصيل ، راجع وثائق حساب الخدمة .

حجم الرمز

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

  • رموز التفويض: 256 بايت
  • رموز الوصول: 2048 بايت
  • تحديث الرموز: 512 بايت

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

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

تحديث انتهاء صلاحية الرمز المميز

يجب عليك كتابة الكود الخاص بك لتوقع احتمالية عدم عمل رمز التحديث الممنوح. قد يتوقف رمز التحديث عن العمل لأحد الأسباب التالية:

  • ألغى المستخدم وصول تطبيقك .
  • لم يتم استخدام رمز التحديث لمدة ستة أشهر.
  • قام المستخدم بتغيير كلمات المرور ويحتوي رمز التحديث المميز على نطاقات Gmail.
  • تجاوز حساب المستخدم الحد الأقصى لعدد رموز التحديث الممنوحة (الحية).
  • ينتمي المستخدم إلى مؤسسة Google Cloud Platform التي لديها سياسات التحكم في الجلسات سارية المفعول.

مشروع Google Cloud Platform مع شاشة موافقة OAuth مهيأة لنوع مستخدم خارجي وحالة نشر "اختبار" يتم إصدار رمز تحديث مميز تنتهي صلاحيته في 7 أيام.

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

يوجد أيضًا حد أكبر للعدد الإجمالي لرموز التحديث التي يمكن أن يمتلكها حساب مستخدم أو حساب خدمة عبر جميع العملاء. لن يتجاوز معظم المستخدمين العاديين هذا الحد ، لكن قد يتعدى حساب المطوِّر المستخدم لاختبار تطبيق ما.

إذا كنت بحاجة إلى تفويض العديد من البرامج أو الأجهزة أو الأجهزة ، فإن أحد الحلول هو تقييد عدد العملاء الذين تسمح لهم لكل حساب Google بـ 15 أو 20. إذا كنت مسؤولاً في Google Workspace ، فيمكنك إنشاء مستخدمين إضافيين بامتيازات إدارية استخدامها لتفويض بعض العملاء.

التعامل مع سياسات التحكم في الجلسات لمؤسسات Google Cloud Platform (GCP)

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

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

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

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

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