Notice: We're retiring Works with Nest. See the home page for more information.
Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

مصادقة OAuth 2.0 والتفويض

يستخدم Nest API بروتوكول OAuth 2.0 للمصادقة والتفويض.

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

يبدأ تسلسل المصادقة عندما يقوم منتجك بإعادة توجيه المستعرض إلى عنوان URL لـ Nest مع معلمات الاستعلام التي تشير إلى الوصول المطلوب. يتعامل Nest مع مصادقة المستخدم واختيار الجلسة وموافقة المستخدم. والنتيجة هي رمز تفويض ، يمكن لمنتجك استبداله برمز وصول. يمكن لمنتجك بعد ذلك استخدام رمز الدخول لإجراء مكالمات إلى Nest API.

تدفق بروتوكول OAuth 2.0
تدفق بروتوكول OAuth 2.0

تكوين أعمالك مع عميل Nest

للعثور على بيانات اعتماد OAuth 2.0 لعميلك ، راجع علامة التبويب "نظرة عامة" لصفحة العميل.

هل تريد إعادة توجيه URI أو التفويض المستند إلى PIN؟

عندما تقوم بتكوين عميلك ، تتم مطالبتك بإدخال URI لإعادة التوجيه أو ترك حقول URI لإعادة التوجيه فارغة لاستخدام التفويض المستند إلى PIN.

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

إذا كان منتجك يحتوي على مكون متصفح ، فإن أفضل ممارسة هي تضمين عنوان URI لإعادة التوجيه.

أذونات طلب

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

نتيجة

عند حفظ التكوين ، يتم تعيين معرف عميل خاص بك وسر عميل خاص بالعميل. بالإضافة إلى ذلك ، يتم تعيين عنوان URL الخاص بالتفويض لعميلك.

يتضمن عنوان URL للتفويض معلمة حالة يمكنك استخدامها لاختبار هجمات تزوير الطلبات عبر المواقع (CSRF) المحتملة. انظر اختبار هجمات CSRF .

تفاصيل OAuth

طلب رمز التفويض

بعد تكوين عميلك ، يمكنك طلب رمز تفويض (يسمى أحيانًا رمز PIN). رمز التفويض ليس الرمز النهائي الذي تستخدمه لإجراء مكالمات إلى Nest. يتم استخدامه في الخطوة التالية من تدفق OAuth 2.0 لتبادل رمز وصول فعلي. توفر هذه الخطوة تأكيدًا مباشرًا من Nest للمستخدم بأنه تم منح الإذن للمنتج الصحيح ، مع الوصول المتفق عليه.

تجربة المستخدم

نقدم صفحة Works with Nest تطلب من المستخدم منح حق الوصول إلى منتجك. يحدد هذا منتجك ويحدد أذونات (نطاقات) مستخدم معينة يطلبها منتجك. تأتي الكلمات الموجودة على الشاشة من تكوين العميل الخاص بك.

لاختبار ذلك بنفسك ، قم بتحميل عنوان URL الخاص بالتفويض من الخطوة 1 في المستعرض. يجب أن تشاهد صفحة طلب الوصول إلى Works with Nest:

يعمل مع Nest

المضي قدما وانقر فوق [قبول] نفسك لمعرفة ما يراه المستخدم. من خلال النقر فوق الزر [قبول] ، يوافق المستخدم على طلب منتجك للوصول إلى بياناته.

تجربة PIN

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

الرقم السري

إعادة توجيه تجربة URI

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

اختبار لهجمات CSRF

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

هجوم CSRF هو هجوم يجبر المستخدم النهائي على تنفيذ إجراءات غير مرغوب فيها على تطبيق ويب تتم مصادقته عليه حاليًا.

هجوم CSRF
هجوم CSRF

للمساعدة في منع هجمات CSRF ، نوصي دائمًا بتقديم state الاستغناء عنها عند طلب الترخيص.

وبهذه الطريقة ، يمكن لتكامل Works with Nest التحقق من أن رموز الوصول التي تم الحصول عليها من سحابة Nest تستجيب للطلبات التي يقدمها منتجك ، وليس بعض المنتجات الأخرى.

مثال:

دعنا نقول في تكوين عميلك ، أنت تحدد URI لإعادة التوجيه:

 http://localhost:5000/callback
 

لنفترض أيضًا أن عميلك يرسل حالة 7tvPJiv8StrAqo9IQE9xsJaDso4 في عنوان URL الخاص بالتفويض:

 https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
 

يوافق المستخدم على الطلب.

تُرجع سحابة Nest معلمة الحالة كجزء من URI لإعادة التوجيه:

 127.0.0.1 - - [02/Jun/2017 13:18:58] "GET /callback?state=7tvPJiv8StrAqo9IQE9xsJaDso4&code=5N4CFK8E8TCFW7PM HTTP/1.1" 302 -
127.0.0.1 - - [02/Jun/2017 13:18:58] "GET / HTTP/1.1" 200 -
 

يتلقى منتجك قيمة هذه الحالة ويجب برمجته لقبول عمليات إعادة التوجيه فقط مع حالة يمكن التحقق منها.

هناك طرق متعددة لإنشاء معلمة حالة لا يمكن تخمينها. يمكنك توفير قيم حالة عشوائية من قاموس محفوظ في الذاكرة أو قيمة قابلة لإعادة التسجيل. يمكنك استخدام مفتاح خاص مع بعض المتغيرات التي يمكن التحقق منها بسهولة - على سبيل المثال ، معرف العميل وملف تعريف ارتباط الجلسة - لحساب قيمة مجزأة. ينتج عن ذلك قيمة بايت يصعب تخمينها بدون المفتاح الخاص. اقتراح آخر هو تجزئة التاريخ والوقت الحاليين. باستخدام هذا النهج ، يجب أن يوفر تطبيقك وقت الإرسال للتحقق منه أو السماح بفترة انزلاق من الصلاحية (على سبيل المثال ، باستخدام خوارزمية كلمة مرور لمرة واحدة [TOTP]).

بعد حساب رمز مصادقة رسالة التجزئة ذات المفاتيح (HMAC) ، يقوم أساس 64 بتشفيرها وتمريرها إلى سحابة Nest كمعلمة حالة.

إليك مثال Python يستخدم datetime :

 import base64
import datetime
import hmac
import hashlib

def generate_state_parameter(client_id, private_key):
    date = datetime.datetime.today()
    raw_state = str(date) + client_id
    hashed = hmac.new(private_key, raw_state, hashlib.sha1)
    state = base64.b64encode(hashed.digest())
    return (state, date)
 

رسائل خطأ كود التفويض

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

رمز ترخيص Exchange لرمز الوصول

الخطوة الأخيرة في الحصول على رمز وصول هي أن يطلب منتجك واحدًا باستخدام رمز التفويض الذي حصل عليه للتو. يتم ذلك عن طريق تقديم طلب HTTP POST "x-www-form-urlencoded".

قم بتضمين المعلمات أدناه في الطلب. جميع المعلمات الأربعة مطلوبة.

معامل وصف
client_id معرف العميل في الخطوة 1
سر العميل سر العميل في الخطوة 1
الشفرة تم استلام رمز التفويض في الخطوة 2
نوع المنحة يجب أن تكون قيمة هذا الحقل دائمًا: authorization_code

قبل كل مكالمة POST ، احصل على رمز تفويض جديد. للقيام بذلك ، أعد تحميل عنوان URL الخاص بالتفويض. ثم قم بتغيير معلمة code POST لتضمين رمز التفويض الجديد.

أمثلة كود (مصادقة)

انظر الأمثلة بلغات مختلفة .

مثال ساعي البريد (مصادقة)

يوفر Postman طريقة سهلة لاختبار طلبات OAuth.

في علامة التبويب " الرؤوس" ، تأكد من Content-Type = application/x-www-form-urlencoded .

رأس POST للحصول على رمز الوصول

على علامة التبويب الجسم، وتشمل المفتاح التالي: أزواج قيمة.

نص POST للحصول على رمز الدخول

استجابة رمز الوصول

يعرض الطلب الناجح كائن JSON يحتوي على الحقول التالية:

  • access_token - رمز الوصول للمستخدم. يجب الحفاظ على هذه القيمة آمنة.
  • expires_in - عدد الثواني المتبقية ، منذ وقت طلبها ، قبل انتهاء صلاحية الرمز المميز.

رسائل خطأ رمز الدخول

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

تقديم طلبات مصدق عليها

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

رموز الدخول صالحة فقط لمجموعة العمليات والموارد الموضحة في نطاق طلب الرمز المميز. على سبيل المثال ، إذا تم إصدار رمز وصول لـ Nest Thermostat API ، فلا يمنح الوصول إلى Nest Camera API.

أمثلة التعليمات البرمجية (قراءة / كتابة)

مثال ساعي البريد (قراءة / كتابة)

يوفر Postman طريقة سهلة لاختبار مكالمات API باستخدام Content-Type = application/json .

احصل على قراءة البيانات

الرموز غير صالحة

إذا قمت بإجراء مكالمة API باستخدام رمز مميز غير صالح ، فستتلقى 401 استجابة غير مصرح بها من الخادم. قد يكون الرمز المميز غير صالح ويحتاج إلى التجديد للأسباب التالية:

  • لقد انتهت صلاحيتها
  • ألغى المستخدم الإذن الذي منحه لمنتجك في البداية

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

تم إغلاق العمل مع اتصال Nest

إذا قام أحد المستخدمين بإزالة اتصال Works with Nest ، يتلقى auth_revoked حدث auth_revoked ويغلق الاتصال.