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

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

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

تقدم هذه الصفحة نظرة عامة على سيناريوهات مصادقة OAuth 2.0 التي تدعمها Google ، وتوفر روابط لمحتوى أكثر تفصيلاً. للحصول على تفاصيل حول استخدام أوث 2.0 للمصادقة، انظر رض الاتصال .

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

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

1. الحصول أوث أوراق اعتماد 2.0 من Google API Console.

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

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

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

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

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

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

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

3. فحص نطاقات الوصول الممنوحة من قبل المستخدم.

قارن النطاقات المضمنة في استجابة رمز الوصول بالنطاقات المطلوبة للوصول إلى ميزات ووظائف تطبيقك التي تعتمد على الوصول إلى واجهة Google API ذات الصلة. قم بتعطيل أي ميزات لتطبيقك غير قادرة على العمل دون الوصول إلى واجهة برمجة التطبيقات ذات الصلة.

قد لا يتطابق النطاق المضمن في طلبك مع النطاق المضمن في استجابتك ، حتى إذا منح المستخدم جميع النطاقات المطلوبة. راجع الوثائق الخاصة بكل Google API للتعرف على النطاقات المطلوبة للوصول. قد تقوم واجهة برمجة التطبيقات بتعيين قيم سلسلة نطاق متعددة إلى نطاق وصول واحد ، مع إعادة نفس سلسلة النطاق لجميع القيم المسموح بها في الطلب. مثال: API جوجل الناس قد ترجع نطاق https://www.googleapis.com/auth/contacts عند طلب التطبيق المستخدم يأذن نطاق https://www.google.com/m8/feeds/ . طريقة API جوجل الناس people.updateContact يتطلب نطاق الممنوحة من https://www.googleapis.com/auth/contacts .

4. إرسال رمز الوصول إلى API.

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

الرموز وصول صالحة فقط لمجموعة من العمليات والموارد وصفها في 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 ، تحديد أن هذا هو التطبيق المثبت، ثم حدد الروبوت، التطبيق كروم، دائرة الرقابة الداخلية، منصة ويندوز العالمي (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 APIs مثل 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 بايت

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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