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

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

المقدمة

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

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

الجمهور

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

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

مصطلحات بسيطة

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

  1. "رقصة OAuth"

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

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

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

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

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

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

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

    هذه هي معرّفات الموارد المنتظمة (URI) المطلوبة لمصادقة تطبيق والحصول على رمز دخول. هناك ثلاث وحدات إجمالية - واحدة لكل خطوة من عملية 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، يكون مقدم الخدمة هذا هو Google. بوجه عام، يتم استخدام مقدم الخدمة لوصف موقع الويب أو خدمة الويب التي توفر نقاط نهاية OAuth. مثال آخر على مقدم خدمة OAuth هو MySpace.

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

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

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

البدء

تسجيل

هناك قدر صغير من الإعداد قبل أن تتمكن من البدء في استخدام OAuth مع واجهات برمجة التطبيقات لبيانات Google. نظرًا لأن جميع طلبات 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 الأساسي المشفر لعنوان 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

الغرض

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

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

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

  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 إلى نطاقك المسجَّل وإدخال مفتاحك الخاص عن طريق النقر على "استخدام مفتاحك الخاص". يُرجى استخدام المفتاح الخاص TEST فقط.

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

بالإضافة إلى RSA-SHA1، يمكنك اختيار استخدام HMAC-SHA1 لـ oauth_signature_method. في هذه الحالة، سيعرض "مساحة المرح" مربعات إضافية حيث ستحتاج إلى إدخال 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. انقر على "إدخال بيانات المشاركة" أسفل القائمة المنسدلة والصِق XML في <entry> في النافذة المنبثقة.
  5. انقر على الزر "تنفيذ".

سيستجيب الخادم باستخدام 200 OK.

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

الخاتمة

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

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

الموارد