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

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

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

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

تتبع جميع التطبيقات نمطًا أساسيًا عند الدخول إلى واجهة برمجة تطبيقات Google باستخدام OAuth 2.0. وفي مستوى عالٍ، يمكنك اتّباع خمس خطوات:

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

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

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

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

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

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

5. أعِد تحميل رمز الدخول إذا لزم الأمر.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يستخدم تطبيق الخادم ملف JWT لطلب رمز مميّز من خادم تفويض Google، ثم يستخدم الرمز المميّز لاستدعاء نقطة نهاية Google API. وليس هناك أي مستخدم نهائي.

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

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

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

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

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

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

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

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

يتم إصدار رمز مميّز لإعادة التحميل ستنتهي صلاحيته خلال 7 أيام في مشروع Google Cloud Platform الذي تم ضبط شاشة موافقة OAuth له على نوع مستخدم خارجي وتكون حالة نشره هي "اختبار"، إلا إذا كانت نطاقات OAuth الوحيدة المطلوبة هي مجموعة فرعية من الاسم وعنوان البريد الإلكتروني والملف الشخصي للمستخدم (من خلال نطاقات userinfo.email, userinfo.profile, openid أو مكافئات OpenID).

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

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

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

التعامل مع سياسات التحكّم في الجلسات للمؤسسات التي تستخدم Google Cloud Platform

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

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

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

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

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