استخدام OAuth مع Google Data APIs

إريك بيدلمان، فريق Google Data APIs
سبتمبر 2008

مقدمة

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

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

الجمهور

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

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

بعض المصطلحات

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

  1. "OAuth dance"

    مصطلح غير رسمي أستخدمه لوصف عملية المصادقة/التفويض الكاملة في OAuth.

  2. (OAuth) رمز الطلب

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

  3. رمز الدخول (OAuth)

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

    التشابه مع AuthSub:
    رمز الدخول عبر OAuth هو نفسه رمز جلسة AuthSub الآمن.

  4. نقاط النهاية (OAuth)

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

    الحصول على رمز مميّز للطلب:https://www.google.com/accounts/OAuthGetRequestToken
    منح الإذن بالرمز المميز للطلب:https://www.google.com/accounts/OAuthAuthorizeToken
    الترقية إلى رمز دخول:https://www.google.com/accounts/OAuthGetAccessToken

    التشابه مع AuthSub:
    إنّ تبادل رمز مميز لطلب معتمد مقابل رمز مميز للدخول يشبه ترقية رمز مميز AuthSub صالح للاستخدام مرة واحدة إلى رمز مميز لجلسة طويلة الأمد على https://www.google.com/accounts/AuthSubRequestToken وhttps://www.google.com/accounts/AuthSubSessionToken على التوالي. والفرق هو أنّ AuthSub لا يتضمّن مفهوم رمز الطلب الأوّلي. بدلاً من ذلك، يبدأ المستخدم عملية الرمز المميّز من صفحة AuthSubRequestToken التفويض.

  5. مقدّم الخدمة (OAuth)

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

  6. المستهلك (OAuth)

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

ملاحظة: على الرغم من أنّ بروتوكول OAuth يتيح حالة استخدام التطبيقات المثبّتة على الكمبيوتر، لا تتيح Google بروتوكول OAuth إلا لتطبيقات الويب.

البدء

التسجيل

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

طلبات التوقيع

بعد تسجيل نطاقك، ستكون مستعدًا لبدء توقيع الطلبات. من أصعب مفاهيم OAuth كيفية إنشاء oauth_signature بشكلٍ سليم ومفهوم سلسلة التوقيع الأساسية. السلسلة الأساسية هي البيانات التي توقّعها باستخدام مفتاحك الخاص (باستخدام RSA_SHA1)، والنتيجة هي القيمة التي تحدّدها لـ oauth_signature.

مثال على الطلب

GET قائمة بتقاويم Google الخاصة بالمستخدم في http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

تنسيق السلسلة الأساسية base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
مثال على السلسلة الأساسية GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
مثال على طلب HTTP 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

ملاحظة: هذا التمثيل لأغراض التوضيح فقط. ستكون مدة oauth_signature أطول بكثير.

ملاحظات حول السلسلة الأساسية:

  • يتم ترتيب مَعلمة طلب البحث orderby=starttime مع بقية المَعلمات oauth_* بترتيب قيمة البايت المعجمي.
  • ولا تحتوي هذه السلسلة أيضًا على الرمز "؟".
  • لا يحتوي الجزء base-http-request-url إلا على عنوان URL الأساسي المرمّز: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • يتم ترميز oauth_token مرتين باستخدام ترميز عنوان URL.

ملاحظات حول العنوان Authorization:

  • لا يهم ترتيب المَعلمات oauth_* في العنوان Authorization.
  • لا يتضمّن العنوان orderby=starttime كما فعلت السلسلة الأساسية. ويتم الاحتفاظ بمَعلمة طلب البحث هذه كجزء من عنوان URL للطلب.

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

الاختلاف عن AuthSub:
للمقارنة، إليك المثال نفسه باستخدام AuthSub الآمنة:

تنسيق السلسلة الأساسية base_string = http-method http-request-URL timestamp nonce
مثال على السلسلة الأساسية 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
مثال على طلب HTTP 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

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

أداة OAuth Playground

الغرض

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

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

ما هي وظيفة هذا الخيار؟

  1. يوضّح عملية المصادقة عبر OAuth: استرداد رمز مميّز للطلب، وتفويض الرمز المميز، وترقيته إلى رمز دخول.
  2. تعرِض هذه السمة سلسلة التوقيع الأساسية الصحيحة لكل طلب.
  3. تعرِض هذه السمة عنوان Authorization الصحيح لكل طلب.
  4. يوضّح هذا المثال كيفية استخدام oauth_token للتفاعل مع خلاصة بيانات Google مصادَق عليها. يمكنك الاطّلاع على بيانات GET/POST/PUT/DELETE.
  5. عرض خلاصة مصادَق عليها مباشرةً في المتصفح
  6. تتيح لك اختبار oauth_consumer_key (نطاقك المسجّل) والمفتاح الخاص.
  7. تعرَّف على خدمات خلاصة بيانات Google المتاحة oauth_token.

تشغيل العرض التوضيحي

الخطوة 1: اختيار النطاقات

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

التشابه مع AuthSub:
يتطلّب AuthSub أيضًا المَعلمة scope للتحكّم في نطاق البيانات التي يمكن أن يصل إليها الرمز المميّز. نفّذت Google هذه المَعلمة كما هو مقترح في مواصفات OAuth.

الخطوة 2: تعديل مَعلمات وإعدادات OAuth

في الوقت الحالي، لا تعدِّل أي إعدادات في المربّع "تعديل مَعلمات OAuth". في وقت لاحق، يمكنك إجراء الاختبار باستخدام مفتاحك الخاص عن طريق تغيير oauth_consumer_key إلى نطاقك المسجّل وإدخال مفتاحك الخاص من خلال النقر على "استخدام مفتاحك الخاص". يُرجى استخدام مفتاح خاص اختباري فقط.

ملاحظة: oauth_signature_method وoauth_consumer_key هما الحقلان الوحيدان اللذان يمكن تعديلهما هنا. سيتم إنشاء oauth_timestamp وoauth_nonce وoauth_token تلقائيًا.

بالإضافة إلى RSA-SHA1، يمكنك اختيار استخدام HMAC-SHA1 في oauth_signature_method. في هذه الحالة، ستعرض Playground مربّعات إضافية حيث عليك إدخال oauth_consumer_key ومفتاح المستهلك الخاصَّين بك. يمكن العثور على هذه القيم في صفحة https://www.google.com/accounts/ManageDomains الخاصة بنطاقك المسجّل.

الاختلاف عن AuthSub:
في AuthSub الآمن، ما مِن مَعلمة لتحديد اسم نطاق بشكل صريح. يتم تضمين النطاق كجزء من مَعلمة عنوان URL next. تتوفّر مَعلمة من هذا النوع في OAuth: oauth_consumer_key. اضبطه على نطاقك المسجَّل.

الخطوات من 3 إلى 5: الحصول على رمز الدخول

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

أولاً، انقر على الزر "طلب رمز مميّز" في المربّع "الحصول على الرمز المميّز".

سيتم ملء حقول معيّنة بالبيانات.

  • تعرض "سلسلة التوقيع الأساسية" الشكل المناسب للسلسلة الأساسية المستخدَمة لإنشاء المَعلمة oauth_signature.
  • يعرض "عنوان التفويض" العنوان Authorization المناسب للطلب.
  • مربّع "تعديل مَعلمات OAuth" مملوء بالقيم oauth_nonce وoauth_timestamp التي تم إرسالها في الطلب.
  • تم ملء حقل الإدخال oauth_token بالقيمة المناسبة التي تم عرضها في نص الاستجابة. تعرض ساحة الألعاب أيضًا نوع oauth_token المتوفّر لدينا حاليًا. في الوقت الحالي، هو رمز طلب.

بعد ذلك، انقر على الزر "تفويض" في المربّع "الحصول على الرمز المميّز".

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

التشابه مع AuthSub:
صفحة التفويض هذه هي نفسها في AuthSub.

الاختلاف عن AuthSub:
تتشابه مَعلمة عنوان URL next في AuthSub مع المَعلمة oauth_callback. الفرق هو أنّ oauth_callback في OAuth هو أمر اختياري. بعد أن ينقر المستخدم على الزر "منح الإذن بالوصول"، يصبح رمز الطلب مميّزًا ومصادقًا عليه، ويمكن إجراء عملية ترقية الرمز المميز إلى https://www.google.com/accounts/OAuthGetAccessToken بشكل غير متزامن.

ملاحظة: يُفضّل تحديد عنوان URL oauth_callback إذا كنت تكتب تطبيق ويب لأنّه يقدّم تجربة أفضل للمستخدم.

أخيرًا، انقر على الزر "رمز الدخول" في المربّع "الحصول على الرمز".

يؤدي هذا الإجراء إلى ترقية رمز طلب الوصول المفوَّض (كما هو موضّح في تصنيف "رمز الدخول" الأحمر).

إذا أردت الحصول على رمز مميّز جديد، انقر على "البدء من جديد" لإعادة بدء عملية OAuth.

الآن يمكننا فعل شيء مثير للاهتمام.

استخدام رمز الدخول

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

ملاحظة: لاستكشاف الخلاصات المتاحة لرمز الدخول، انقر على الزر "الخلاصات المتاحة".

إليك مثال على طلب بحث: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

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

مثال: كيفية تعديل مشاركة

  1. ابحث عن العنصر <link> الذي يتضمّن rel="edit" في المشاركة التي تريد تعديلها. يجب أن يبدو على النحو التالي: 
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

    ألصِق عنوان URL الخاص بـ href في حقل الإدخال "إدخال خلاصة بيانات Google".

  2. انسخ XML للإدخال الحالي من خلال النقر على "عرض النص العادي" في أعلى اللوحة التي تم فيها تمييز البنية. انسخ نص الردّ فقط، وليس العناوين.
  3. غيِّر القائمة المنسدلة لطريقة HTTP إلى PUT.
  4. انقر على "إدخال بيانات النشر" أسفل تلك القائمة المنسدلة وألصِق <entry> XML في النافذة المنبثقة.
  5. انقر على الزرّ "تنفيذ".

سيردّ الخادم برمز 200 OK.

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

الخاتمة

تساعد تقنيات مثل بروتوكول AtomPub/Atom Publishing (البروتوكول الأساسي لواجهات Google Data APIs) وOAuth في تطوير الويب. ومع بدء المزيد من المواقع الإلكترونية في اعتماد هذه المعايير، سنكون نحن المطوّرين المستفيدين. أصبح إنشاء تطبيق ناجح أقل صعوبة.

إذا كانت لديك أي أسئلة أو تعليقات حول OAuth Playground أو استخدام OAuth مع Google APIs، يُرجى زيارتنا في منتدى الدعم الخاص بواجهات G Suite APIs وMarketplace APIs.

الموارد