المصادقة والتفويض في بروتوكول بيانات Google

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

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

تتيح خدمات المصادقة للمستخدمين تسجيل الدخول إلى تطبيقك باستخدام حساب Google.

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

يُشار غالبًا إلى خدمات المصادقة والترخيص بشكل جماعي باسم auth.

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

  • توفّر خدمة تسجيل الدخول باستخدام حساب Google طريقة بسيطة تتيح للمستخدمين استخدام بيانات اعتماد حساباتهم على Google لتسجيل الدخول إلى موقعك الإلكتروني. تتضمّن مجموعة من الأدوات التي يسهل دمجها على الأجهزة المختلفة.
  • OAuth 2.0 هو بروتوكول تفويض لجميع Google APIs. يعتمد بروتوكول OAuth 2.0 على بروتوكول SSL لتوفير الأمان بدلاً من أن يطلب من تطبيقك إجراء التوقيعات المشفرة مباشرةً. يسمح هذا البروتوكول لتطبيقك بطلب الوصول إلى البيانات المرتبطة بحساب المستخدم على Google.
  • تتيح ميزة تسجيل الدخول باستخدام بروتوكول OAuth 2.0 (اتصال OpenID) للمستخدمين المصادقة من خلال تسجيل الدخول باستخدام حساباتهم على Google. هذه الميزة هي بديل عن OpenID، وعلى مستخدمي OpenID التخطيط للانتقال إلى ميزة "تسجيل الدخول باستخدام OAuth 2.0".

إذا كان تطبيقك عبارة عن أداة (للاستخدام في iGoogle أو حاويات OpenSocial الأخرى)، يُرجى الاطّلاع على القسم المصادقة للأدوات.

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

يمكنك أيضًا الاطّلاع على مجموعة Google Accounts API لمناقشة استخدام واجهات Google Accounts API.

OAuth - منح الإذن لتطبيقات الويب والتطبيقات المثبّتة

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

تتيح Google إصدارَين من بروتوكول OAuth للحصول على إذن بالوصول إلى بيانات المستخدم على Google، وهما OAuth 1.0 وOAuth 2.0، ويتيح كلاهما الوصول إلى تطبيقات الويب والتطبيقات المثبَّتة.

بروتوكول OAuth 2.0 لتطبيقات الويب والتطبيقات المثبَّتة

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

‫OAuth 1.0 لتطبيقات الويب

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

بروتوكول OAuth 1.0 للتطبيقات المثبَّتة

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

استخدام OAuth مع تطبيقات الويب

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

توفّر مكتبات عميل Google Data APIs طرقًا لمساعدتك في استخدام OAuth في تطبيق الويب. على وجه التحديد، هناك طرق لإنشاء رمز الطلب، ومنح الإذن لرمز الطلب، واستبدال رمز الطلب الذي تم منح الإذن له برمز دخول. تتعامل المكتبات أيضًا مع خوارزميات التوقيع اللازمة عند تقديم طلبات إلى إحدى خدمات "بيانات Google". للاطّلاع على أمثلة شاملة حول كيفية استخدام بروتوكول OAuth مع مكتبات عميل Google Data API، يُرجى الاطّلاع على استخدام بروتوكول OAuth مع مكتبات عميل Google Data API.

عملية تفويض OAuth

تتضمّن عملية تفويض OAuth سلسلة من التفاعلات بين تطبيق الويب وخوادم التفويض من Google والمستخدم النهائي.

على المستوى الأساسي، تكون العملية على النحو التالي:

  1. يطلب تطبيقك إذن الوصول ويحصل على رمز مميز غير مصرح به من خادم التفويض التابع لـ Google.
  2. تطلب Google من المستخدم منحك إذن الوصول إلى البيانات المطلوبة.
  3. يحصل تطبيقك على رمز مميز لطلب معتمد من خادم التفويض.
  4. يمكنك استبدال رمز طلب معتمَد برمز دخول.
  5. يمكنك استخدام رمز الدخول المميز لطلب بيانات من خوادم الوصول إلى خدمات Google.

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

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

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

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

الاستعداد لاستخدام OAuth

قبل إعداد تطبيقك لاستخدام خدمة "الترخيص من Google" مع OAuth، يجب إكمال المهام التالية.

تحديد ما إذا كان يجب تسجيل تطبيق الويب

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

يجب أن يوقّع تطبيقك كل طلب OAuth يقدّمه. إذا اخترت استخدام توقيع RSA-SHA1 لتوقيع طلباتك، عليك تحميل شهادة أمان كجزء من عملية التسجيل.

بدلاً من ذلك، يمكنك استخدام توقيع HMAC-SHA1 لتوقيع طلباتك. لا يلزم توفّر شهادة لتوقيعات HMAC-SHA1. بدلاً من ذلك، تنشئ Google قيمة consumer secret لبروتوكول OAuth، ويتم عرضها في صفحة تسجيل نطاقك بعد إتمام عملية التسجيل.

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

تحديد نطاق البيانات التي سيصل إليها تطبيقك

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

بشكل عام، يجب طلب رمز مميّز لأضيق نطاق يتضمّن البيانات التي تحتاج إليها. على سبيل المثال، إذا كان تطبيقك يتطلّب الوصول إلى خلاصة "جميع التقاويم" الخاصة بالمستخدم، عليك طلب رمز مميّز للنطاق http://www.google.com/calendar/feeds/default/allcalendars/full.

إعداد آلية لإدارة رموز OAuth المميزة

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

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

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

إعداد آلية لطلب الوصول إلى إحدى خدمات Google

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

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

تنفيذ OpenID (اختياري)

إذا كنت بصدد تنفيذ OpenID لمصادقة المستخدمين، ننصحك باستخدام البروتوكول المختلط للجمع بين العمليتين. باستخدام OpenID+OAuth، يتم التعامل مع مهام الحصول على رمز مميز للطلب والموافقة عليه كجزء من طلب OpenID مع إضافات OAuth. كما هو الحال مع OAuthGetRequestToken، يتم استخدام هذه الامتدادات لتحديد خدمات Google التي سيتم الوصول إليها. تحتوي الاستجابة الناجحة لطلب OpenID على رمز مميّز لطلب معتمد. بعد تلقّي هذا الرمز المميّز، استخدِم OAuthGetAccessToken لاستبداله برمز دخول.

التعامل مع رموز OAuth المميزة

لاستخدام OAuth، يجب أن ينشئ تطبيقك طلبات رموز مميّزة موقعة ومنسّقة بشكل جيد، وأن يتعامل مع الردود، وذلك وفقًا للتسلسل التالي:

  1. الحصول على رمز مميّز لطلب غير مصرح به (OAuthGetRequestToken)
  2. تفويض رمز الطلب (OAuthAuthorizeToken)
  3. استبدال رمز الطلب المصرّح به برمز دخول (OAuthGetAccessToken)

يجب توقيع جميع طلبات OAuth، سواء كان تطبيقك مسجّلاً أم لا. لمزيد من المعلومات، يُرجى الاطّلاع على توقيع طلبات OAuth.

يمكنك تجربة طلب رموز التفويض وتلقّيها في OAuth Playground.

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

ضبط عنوان URL لرد الاتصال

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

على سبيل المثال، عند توفير دعم للغات متعددة، يمكنك تضمين مَعلمة طلب بحث تحدّد إصدار التطبيق الذي يعرضه المستخدم. ستؤدي قيمة oauth_callback التي تساوي "http://www.yoursite.com/Retrievetoken?Lang=de إلى إعادة التوجيه "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". يضمن تحليل الرمز المميّز ومعلَمة اللغة إعادة توجيه المستخدم إلى النسخة الصحيحة من الموقع الإلكتروني.

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

تحديد هوية تطبيقك للمستخدمين

يعرض Google عادةً اسم التطبيق عند طلب موافقة المستخدم على الوصول إلى بياناته (اطّلِع على المثال).

إذا لم يكن تطبيقك مسجّلاً، استخدِم المَعلمة xoauth_displayname في طلب OAuthGetRequestToken لتحديد اسم تطبيقك. إذا لم يتم تحديد هذه المَعلمة، تعرض Google اسم النطاق الخاص بعنوان URL المقدَّم من خلال المَعلمة oauth_callback. إذا لم يتم تقديم عنوان URL لبرنامج معالجة، تعرض Google السلسلة "مجهول".

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

ملاحظة: لضبط المَعلمة xoauth_displayname في OAuth Playground، ضَع علامة في المربّع "متقدّم" قبل جلب رمز الطلب.

العمل مع نطاقات Google Apps

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

مزيد من المعلومات حول OAuth

للحصول على معلومات تفصيلية حول تنفيذ Google لبروتوكول OAuth، بما في ذلك كيفية تسجيل تطبيقك وإنشاء مَعلمات OAuth اللازمة، راجِع المراجع الإضافية التالية:

الرجوع إلى الأعلى

استخدام OAuth مع التطبيقات المثبَّتة

تتوافق جميع واجهات Google Data APIs مع OAuth، وهو معيار مفتوح لتفويض استخدام البيانات في التطبيقات. لا يلزم تسجيل التطبيقات المثبَّتة لدى Google لاستخدام بروتوكول OAuth.

عملية تفويض OAuth

تتضمّن عملية تفويض OAuth سلسلة من التفاعلات بين تطبيقك وخوادم التفويض من Google والمستخدم النهائي.

على المستوى الأساسي، تكون العملية على النحو التالي:

  1. يطلب تطبيقك إذن الوصول ويحصل على رمز مميز غير مصرح به من خادم التفويض التابع لـ Google.
  2. تطلب Google من المستخدم منحك إذن الوصول إلى البيانات المطلوبة.
  3. يحصل تطبيقك على رمز مميز لطلب معتمد من خادم التفويض.
  4. يمكنك استبدال رمز طلب معتمَد برمز دخول.
  5. يمكنك استخدام رمز الدخول المميز لطلب بيانات من خوادم الوصول إلى خدمات Google.

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

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

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

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

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

الاستعداد لاستخدام OAuth

قبل إعداد تطبيقك لاستخدام خدمة "الترخيص من Google" مع OAuth، يجب إكمال المهام التالية.

تحديد نطاق البيانات التي سيصل إليها تطبيقك

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

بشكل عام، يجب طلب رمز مميّز لأضيق نطاق يتضمّن البيانات التي تحتاج إليها. على سبيل المثال، إذا كان تطبيقك يتطلّب الوصول إلى خلاصة "جميع التقاويم" الخاصة بالمستخدم، عليك طلب رمز مميّز للنطاق http://www.google.com/calendar/feeds/default/allcalendars/full.

إعداد آلية لإدارة رموز OAuth المميزة

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

يجب أن يدير تطبيقك عملية تخزين الرموز المميزة بشكل آمن، بما في ذلك تتبُّع خدمة Google التي يكون كل رمز مميز صالحًا لها.

إذا كان تطبيقك يتيح استخدام حسابات مستخدمين متعددة، عليك تتبُّع الحساب المرتبط بكل رمز مميّز.

إعداد آلية لطلب الوصول إلى إحدى خدمات Google

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

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

التعامل مع رموز OAuth المميزة

لاستخدام OAuth، يجب أن ينشئ تطبيقك طلبات رموز مميّزة موقعة ومنسّقة بشكل جيد، وأن يتعامل مع الردود، وذلك وفقًا للتسلسل التالي:

  1. الحصول على رمز مميّز لطلب غير مصرح به (OAuthGetRequestToken)
  2. تفويض رمز الطلب (OAuthAuthorizeToken)
  3. استبدال رمز الطلب المصرّح به برمز دخول (OAuthGetAccessToken)

يجب توقيع جميع طلبات OAuth، سواء كان تطبيقك مسجّلاً أم لا. لمزيد من المعلومات، يُرجى الاطّلاع على توقيع طلبات OAuth. يجب أن تتّبع التطبيقات المثبَّتة التعليمات الخاصة بالتطبيقات غير المسجّلة.

يمكنك تجربة طلب رموز التفويض وتلقّيها في OAuth Playground.

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

تحديد هوية تطبيقك للمستخدمين

يعرض Google عادةً اسم التطبيق عند طلب موافقة المستخدم على الوصول إلى بياناته (اطّلِع على المثال).

استخدِم المَعلمة xoauth_displayname في طلب OAuthGetRequestToken لتحديد اسم تطبيقك. إذا لم يتم تحديد هذه المَعلمة، تعرض Google اسم النطاق الخاص بعنوان URL المقدَّم من خلال المَعلمة oauth_callback. إذا لم يتم تقديم عنوان URL لبرنامج معالجة، تعرض Google السلسلة "مجهول".

ملاحظة: لضبط المَعلمة xoauth_displayname في OAuth Playground، ضَع علامة في المربّع "متقدّم" قبل جلب رمز الطلب.

تشغيل متصفّح ويب

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

  • يجب استخدام وضع "الرصد التلقائي" لمعظم التطبيقات
  • يجب استخدام وضع الجهاز للتطبيقات التي لا يمكنها تشغيل متصفّح ويب كامل.
  • يجب استخدام وضع التطوير أثناء مراحل التطوير المبكرة فقط.

وضع "الرصد التلقائي"

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

يتطلّب هذا الوضع توفير عنوان URL لمعاودة الاتصال يتم توجيه المستخدم إليه بعد أن يمنحك الإذن بالوصول. يجب تقديم عنوان URL هذا كالمَعلمة oauth_callback في طلب OAuthGetRequestToken، وكالمَعلمة verifier في طلب OAuthGetAccessToken.

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

لمزيد من المعلومات وأفضل الممارسات، يُرجى الاطّلاع على الرصد التلقائي للموافقة.

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

وضع الجهاز

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

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

وضع التطوير

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

كما هو الحال في وضع AutoDetect، يجب أن يفتح تطبيقك متصفّحًا، ويجب أن يوافق المستخدم على طلبك. ومع ذلك، بدلاً من إنشاء صفحة ويب لعنوان URL لرد الاتصال، يمكنك ضبط قيمة المَعلمة oauth_callback على "oob" (خارج النطاق).

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

على المستخدم العودة إلى تطبيقك وإدخال رقم التأكيد قبل أن تتمكّن من إرسال طلب OAuthGetAccessToken.

مزيد من المعلومات حول OAuth

للحصول على معلومات تفصيلية حول تنفيذ Google لبروتوكول OAuth، بما في ذلك كيفية تسجيل تطبيقك وإنشاء مَعلمات OAuth اللازمة، راجِع المراجع الإضافية التالية:

الرجوع إلى الأعلى

استخدام AuthSub للتفويض

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

عملية التفويض في AuthSub

يتضمّن التفويض باستخدام AuthSub سلسلة من التفاعلات بين ثلاثة كيانات: تطبيق الويب وخدمات Google والمستخدم. يوضّح هذا الرسم التخطيطي التسلسل التالي:

عملية التفويض

  1. عندما يحتاج تطبيق الويب إلى الوصول إلى إحدى خدمات Google الخاصة بالمستخدم، يُجري طلب AuthSub إلى خدمة "خادم وكيل التفويض" من Google.
  2. تستجيب خدمة "الترخيص" من خلال عرض صفحة "طلب الوصول". تطلب هذه الصفحة التي تديرها Google من المستخدم منح/رفض إذن الوصول إلى خدمة Google. قد يُطلب من المستخدم أولاً تسجيل الدخول إلى حسابه.
  3. يقرّر المستخدم ما إذا كان سيمنح تطبيق الويب إذن الوصول أو يرفضه. إذا رفض المستخدم منح الإذن، سيتم توجيهه إلى صفحة Google بدلاً من العودة إلى تطبيق الويب.
  4. إذا منح المستخدم إذن الوصول، تعيد خدمة "الترخيص" توجيهه إلى تطبيق الويب. تحتوي عملية إعادة التوجيه على رمز مميّز للتفويض صالح للاستخدام مرة واحدة، ويمكن استبداله برمز مميّز طويل الأمد.
  5. يتواصل تطبيق الويب مع خدمة Google لإرسال طلب، وذلك باستخدام رمز التفويض المميز للعمل كوكيل للمستخدم.
  6. إذا تعرفت خدمة Google على الرمز المميز، فإنّها تقدّم البيانات المطلوبة.

العمل مع AuthSub

يتطلّب دمج AuthSub في تطبيق الويب تنفيذ المهام التالية:

  1. تحديد ما إذا كنت تريد تسجيل تطبيق الويب أم لا

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

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

  2. حدِّد نوع الرموز المميزة التي تريد استخدامها وكيفية إدارتها.

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

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

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

  3. تحديد النطاق المطلوب الوصول إليه من خلال خدمة Google

    تحدّد كل خدمة من خدمات Google مقدار الوصول ونوعه الذي ستسمح به. يتم التعبير عن هذا الإذن كقيمة نطاق. قد يكون نطاق الخدمة عنوان URL بسيطًا يحدّد الخدمة بأكملها، أو قد يحدّد وصولاً أكثر تقييدًا. تفرض بعض الخدمات قيودًا صارمة على إمكانية الوصول، مثل السماح بالوصول للقراءة فقط إلى معلومات محدودة. للحصول على النطاقات المسموح بها لخدمة Google التي تريد الوصول إليها، راجِع مستندات تلك الخدمة. يجب طلب رمز مميّز بأضيق نطاق ممكن. على سبيل المثال، إذا كنت تحاول الوصول إلى ميزة خلاصة Atom في Gmail، استخدِم النطاق "http://www.google.com/calendar/feeds/"، وليس "http://www.google.com/calendar/". تكون خدمات Google أكثر تقييدًا عند تقديم طلبات ذات نطاق واسع.

  4. إعداد آلية لطلب رمز مميّز للتفويض وتلقّيه

    يجب أن تنشئ الآلية طلب AuthSubRequest سليم التنسيق، بما في ذلك تحديد قيم عنوان URL المناسبة next وscope (المحدّدة في الخطوة 3). إذا كنت تستخدم رموزًا مميّزة آمنة و/أو تدير رموزًا مميّزة للجلسات، يجب أن يتضمّن الطلب قيمًا لهذه المتغيّرات أيضًا.

    يمكن أن يتضمّن عنوان URL التالي مَعلمات طلب البحث. على سبيل المثال، عند توفير دعم للغات متعددة، أدرِج مَعلمة طلب بحث تحدّد إصدار تطبيق الويب الذي يعرضه المستخدم. ستؤدي قيمة next‏ http://www.yoursite.com/Retrievetoken?Lang=de إلى إعادة التوجيه http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. يضمن تحليل الرمز المميّز ومَعلمة Lang إعادة توجيه المستخدم إلى النسخة الصحيحة من الموقع الإلكتروني.

    في ظروف معيّنة، يمكن أن يساعد استخدام المَعلمة hd في تبسيط تجربة المستخدمين عندما يُطلب منهم منح إذن الوصول على موقع "حسابات Google". في معظم الحالات، تكون العملية بسيطة وتتطلّب تسجيل الدخول إلى الحساب واختيار ما إذا كان سيتم منح الإذن بالوصول أم لا. أما المستخدمون الذين لديهم أكثر من حساب على Google (حساب عادي على Gmail و/أو حساب واحد أو أكثر من حسابات Google Apps المستضافة)، فقد يحتاجون إلى اتّباع عملية "تسجيل الدخول الشامل" الإضافية لتحديد الحساب الذي يريدون الوصول إليه. إذا كان تطبيقك مصمّمًا لنطاق مُدار معيّن، يمكنك إلغاء هذه الخطوات الإضافية باستخدام هذه المَعلمة لتحديد هذا النطاق. يمكنك أيضًا استخدام المَعلمة hd إذا كان تطبيقك يصل إلى خدمات غير متاحة على الحسابات المستضافة، وسيؤدي ضبط القيمة على "default" إلى حصر التفويض على الحسابات العادية فقط. عند ضبط قيمة hd، ستختار Google تلقائيًا الحساب الصحيح لمنح الإذن.

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

  5. إعداد آليات لطلب رموز الجلسات وتخزينها أو إبطالها، إذا كان ذلك مناسبًا

    استنادًا إلى قرارات إدارة الرموز المميزة التي اتّخذتها في الخطوة 2، قد تحتاج إلى إنشاء آليات للحصول على رموز الجلسات وإبطالها (AuthSubSessionToken وAuthSubRevokeToken). لاختبار آليات الجلسة والإبطال، استخدِم AuthSubTokenInfo، الذي يشير إلى ما إذا كان الرمز المميّز المحدّد صالحًا أم لا. في حال تخزين الرموز المميزة، يجب أن يتتبّع التطبيق كلاً من معرّف المستخدم والخدمة (النطاق) التي يغطيها الرمز المميز.

  6. إعداد آلية لطلب الوصول إلى إحدى خدمات Google

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

    يجب أن يكون عنوان الطلب بالشكل التالي:

    Authorization: AuthSub token="token"

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

    يوضّح المثال أدناه عنوان طلب لإجراء مكالمة إلى خدمة خلاصة "تقويم Google". يحتوي هذا الطلب على رمز مميز غير آمن: 

    GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

مزيد من المعلومات حول AuthSub

للحصول على معلومات حول AuthSub، بما في ذلك تسجيل تطبيقك لدى Google وشرح مفصّل حول استبدال رمز مميّز صالح لمرة واحدة برمز مميّز للجلسة، يُرجى الاطّلاع على المراجع الإضافية التالية:

الرجوع إلى الأعلى

استخدام ClientLogin للحصول على إذن

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

المصادقة للتطبيقات المثبَّتة: ClientLogin

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

ملاحظة: توفّر مكتبات برامج Google Data APIs طرقًا لمساعدتك في استخدام ClientLogin في التطبيقات المثبّتة. على وجه التحديد، هناك طرق للحصول على رمز مميّز للمصادقة، والتعامل مع تحديات CAPTCHA، واسترجاع رمز المصادقة لاستخدامه لاحقًا، وإرسال عنوان Authorization الصحيح مع كل طلب. إذا كنت تعمل مع إحدى المكتبات، راجِع استخدام ClientLogin مع مكتبات عملاء Google Data APIs.

عملية تفويض ClientLogin

يتضمّن التفويض باستخدام ClientLogin سلسلة من التفاعلات بين ثلاثة عناصر: التطبيق المثبَّت وخدمات Google والمستخدم. يوضّح هذا الرسم التخطيطي التسلسل التالي:

عملية التفويض

  1. عندما يحتاج تطبيق تابع لجهة خارجية إلى الوصول إلى إحدى خدمات Google الخاصة بمستخدم، يسترد التطبيق اسم تسجيل الدخول وكلمة المرور الخاصين بالمستخدم.
  2. بعد ذلك، يرسل التطبيق التابع لجهة خارجية طلب ClientLogin إلى خدمة التفويض في Google.
  3. إذا قرّرت خدمة "منح الإذن في Google" أنّ التحقّق الإضافي ضروري، سترسل ردًّا يشير إلى حدوث خطأ ويتضمّن رمزًا مميزًا وتحديًا من CAPTCHA، وذلك في شكل عنوان URL لصورة CAPTCHA.
  4. في حال تلقّي اختبار CAPTCHA، يعرض التطبيق التابع لجهة خارجية صورة CAPTCHA للمستخدم ويطلب منه تقديم إجابة.
  5. إذا طُلب منه ذلك، يرسل المستخدم إجابة عن اختبار CAPTCHA.
  6. يُجري التطبيق التابع لجهة خارجية طلب ClientLogin جديدًا، ويتضمّن هذه المرة إجابة CAPTCHA والرمز المميّز (الذي تم تلقّيه مع استجابة الخطأ).
  7. عند محاولة تسجيل الدخول بنجاح (مع أو بدون اختبار CAPTCHA)، تعرض خدمة "منح الإذن في Google" رمزًا مميزًا للتطبيق.
  8. يتواصل التطبيق مع خدمة Google لطلب الوصول إلى البيانات، مع الإشارة إلى الرمز المميز الذي تم تلقّيه من خدمة التفويض من Google.
  9. إذا تعرّفت خدمة Google على الرمز المميز، ستوفّر إذن الوصول إلى البيانات المطلوبة.

استخدام ClientLogin

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

يتطلّب دمج ClientLogin في تطبيقك تنفيذ المهام التالية:

  1. أنشئ عنصر واجهة مستخدم لتسجيل بيانات تسجيل الدخول من المستخدم.

    يجب أن تطلب واجهة المستخدم اسم مستخدم (عنوان بريد إلكتروني يتضمّن النطاق) وكلمة مرور. يجب أن تكون واجهة المستخدم قادرة أيضًا على عرض صورة CAPTCHA باستخدام عنوان URL الذي تم تلقّيه من Google، إذا كان ذلك مطلوبًا، وطلب إجابة صحيحة من المستخدم. من المفترض أن تتضمّن واجهة المستخدم رابطًا إلى صفحة تسجيل الدخول إلى حسابات Google ‏(https://www.google.com/accounts/Login) في حال احتاج المستخدم إلى الاشتراك في حساب جديد أو إجراء صيانة أخرى للحساب.

  2. اكتب رمزًا برمجيًا لإنشاء طلب HTTPS POST ClientLogin سليم وتمريره.

    يجب أن يتضمّن هذا الرمز منطقًا للتعامل مع اختبار CAPTCHA، وأن يشمل المَعلمتَين logintoken وlogincaptcha. يجب أن يكون التطبيق قادرًا أيضًا على رصد الحالات التي يحذف فيها المستخدم معلومات مطلوبة أو يكرّر بيانات غير صحيحة بعد تعذُّر تسجيل الدخول، وعرض رسالة خطأ بدون إرسال طلب غير ضروري.

  3. التعامل مع الردود من Google

    هناك أربعة ردود محتملة على طلب تسجيل الدخول:

    • نجاح (HTTP 200)
    • تعذُّر (HTTP 403) مع رمز خطأ توضيحي
    • طلب غير صالح، ينتج عادةً عن طلب تمت صياغته بطريقة غير صحيحة
    • فشل في اجتياز اختبار CAPTCHA

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

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

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

  4. التعامل مع تحدّي CAPTCHA من Google

    للتعامل مع التحدّي، يجب أن يعرض التطبيق صورة CAPTCHA ويطلب من المستخدم تقديم إجابة. لعرض صورة CAPTCHA، استخدِم قيمة CaptchaUrl التي تم إرجاعها مع استجابة الخطأ، مع إضافة البادئة بعنوان URL الخاص بحسابات Google: "http://www.google.com/accounts/". بعد أن يقدّم المستخدم إجابة، على التطبيق إعادة إرسال طلب تسجيل الدخول، مع تضمين رمز CAPTCHA (logintoken) وإجابة المستخدم (logincaptcha). تتحقّق Google من إجابة المستخدم قبل السماح له بالوصول إلى الحساب.

    يتوفّر بديل للمطوّرين الذين لا يريدون إدارة عمليات الحصول على استجابة CAPTCHA من المستخدم ونقلها. استجابةً لتحدّي CAPTCHA، يمكن للتطبيق توجيه المستخدم إلى الصفحة التي تستضيفها Google: "https://www.google.com/accounts/DisplayUnlockCaptcha". بعد أن يجيب المستخدم عن سؤال التحقّق بنجاح، يثق خادم Google في الكمبيوتر المستخدَم. يمكن للتطبيق بعد ذلك إعادة إرسال طلب تسجيل الدخول الأصلي للحصول على رمز التفويض.

    5. ملاحظة: لا تتحقّق Google من محاولة تسجيل الدخول قبل عرض اختبار CAPTCHA. وهذا يعني أنّ محاولة تسجيل الدخول قد تفشل حتى بعد اجتياز اختبار CAPTCHA.

* CAPTCHA هي علامة تجارية مسجّلة تابعة لجامعة كارنيغي ميلون

الرجوع إلى الأعلى

المصادقة على الأدوات

خادم وكيل OAuth

إذا كنت بصدد إنشاء أداة باستخدام Gadgets API العادية، يمكنك الاستفادة من ميزة في منصة الأدوات تُعرف باسم OAuth Proxy للوصول إلى Google Data APIs. ‫OAuth (الموضّح أعلاه) هو معيار مصادقة يتيح للمستخدمين الوصول إلى بياناتهم الخاصة في خدمة استضافة أدوات مثل iGoogle أو MySpace أو Orkut، أو مشاركة بياناتهم مع موقع إلكتروني أو أداة أخرى. تم تصميم خادم وكيل OAuth لتسهيل عملية التطوير على مطوّري الأدوات من خلال إخفاء العديد من تفاصيل المصادقة في OAuth. يستند الخادم الوكيل إلى مشروع مفتوح المصدر يُسمى Shindig، وهو عبارة عن تنفيذ لمواصفات الأداة.

ملاحظة: لا تتوفّر خدمة OAuth Proxy إلا للأدوات التي تستخدم واجهة برمجة التطبيقات gadgets.* وتعمل في حاويات OpenSocial. وهي غير متاحة لواجهة برمجة التطبيقات للأدوات القديمة.

مسار المصادقة

يجب أن يحصل الأداة على رمز مميّز OAuth قبل أن تتمكّن من الوصول إلى بيانات المستخدم. يدير OAuth Proxy عملية المصادقة نيابةً عنك. عندما يثبّت المستخدم الأداة للمرة الأولى، تحدث العملية التالية:

  1. يتم تحميل الأداة للمرة الأولى وتحاول الوصول إلى بيانات المستخدم باستخدام إحدى واجهات Google Data APIs.
  2. يتعذّر تنفيذ الطلب لأنّ المستخدم لم يمنح إذن الوصول. يحتوي عنصر الاستجابة على عنوان URL (في response.oauthApprovalUrl) لصفحة الموافقة على OAuth. يجب أن توفّر الأداة طريقة لفتح نافذة جديدة باستخدام عنوان URL هذا.
  3. في صفحة الموافقة، يختار المستخدم منح إذن الوصول إلى أداتك أو رفضه. في حال نجاح العملية، سيتم نقل المستخدم إلى صفحة oauth_callback التي تحدّدها. للحصول على أفضل تجربة للمستخدم، استخدِم http://oauth.gmodules.com/gadgets/oauthcallback.
  4. بعد ذلك، يغلق المستخدم النافذة المنبثقة. لإعلام الأداة بأنّ المستخدم قد وافق، يمكنك استخدام معالج النوافذ المنبثقة لرصد إغلاق نافذة الموافقة. بدلاً من ذلك، يمكن أن تعرض الأداة رابطًا (مثل لقد وافقت على الوصول) لينقر عليه المستخدم بعد إغلاق هذه النافذة.
  5. يحاول تطبيقك المصغّر الوصول إلى Google Data API مرة ثانية عن طريق إعادة طلب بيانات المستخدم. نجحت هذه المحاولة.
  6. تمت مصادقة الأداة ويمكنها بدء التشغيل بشكل طبيعي.

إعداد الأداة

للوصول إلى واحدة أو أكثر من Google Data APIs، عليك أولاً أن تطلب من الأداة استخدام OAuth كطريقة مصادقة. أضِف عنصر <OAuth> في القسم <ModulePrefs> من ملف XML الخاص بالأداة:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

في هذا القسم، غيِّر مَعلمات طلب البحث التالية فقط:

scope
مَعلمة مطلوبة في عنوان URL للطلب يمكن للأداة الوصول إلى البيانات من scope المستخدَمة في هذه المَعلمة. في هذا المثال، يمكن للأداة الوصول إلى بيانات Blogger و"تقويم Google". يمكن أن يطلب الأداة بيانات لنطاق واحد أو نطاقات متعددة، كما هو الحال في هذا المثال.
oauth_callback
مَعلمة اختيارية في عنوان URL الخاص بالتفويض تتم إعادة توجيه صفحة الموافقة على OAuth إلى عنوان URL هذا بعد أن يوافق المستخدم على الوصول إلى البيانات. يجب ضبط هذه المَعلمة على http://oauth.gmodules.com/gadgets/oauthcallback لتوفير أفضل تجربة للمستخدمين عند تثبيت أداتك. توفّر هذه الصفحة مقتطفًا من JavaScript يغلق النافذة المنبثقة تلقائيًا. بدلاً من ذلك، يمكنك ضبط هذه المَعلمة لتشير إلى صفحتك "الموافَق عليها"، أو يمكنك ببساطة ترك المَعلمة فارغة.

الوصول إلى خلاصة تمت مصادقتها من Google Data API

بعد أن يثبت أداتك هوية المستخدم، يصبح الوصول إلى إحدى واجهات Google Data API أمرًا سهلاً باستخدام مكتبة برامج عميل JavaScript الخاصة بواجهات Google Data API. للحصول على معلومات حول كيفية استخدام المكتبة في خادم وكيل OAuth، يُرجى الاطّلاع على استخدام مكتبة برامج JavaScript.

مزيد من المعلومات حول الأدوات

للحصول على معلومات كاملة حول إنشاء أدوات Google Data API، بما في ذلك تفاصيل حول خادم وكيل OAuth ومقالة حول كيفية البدء ومواصفات gadgets.*، يُرجى الاطّلاع على المراجع الإضافية التالية:

الرجوع إلى الأعلى