Google متعهد به پیشبرد برابری نژادی برای جوامع سیاه است. ببینید چگونه.
این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.
Switch to English

احراز هویت و مجوز OAuth 2.0

Nest API برای تأیید اعتبار و مجوز از پروتکل OAuth 2.0 استفاده می کند.

قبل از اینکه محصول شما با استفاده از API Nest بتواند به داده های خصوصی دسترسی پیدا کند ، باید یک نشانه دسترسی داشته باشد که به آن API دسترسی می دهد. یک نشانه دسترسی واحد می تواند درجات مختلفی از دسترسی به بخش های مختلف API را اعطا کند.

دنباله مجوز از وقتی شروع می شود که محصول شما یک مرورگر را به URL Nest (لانه) هدایت کند با پارامترهای پرس و جو که نشانگر دسترسی درخواستی است. Nest با هویت کاربر ، انتخاب جلسه و رضایت کاربر کنترل می کند. نتیجه یک کد مجوز است ، که محصول شما می تواند یک کد دسترسی را جایگزین کند. سپس محصول شما می تواند از نشانه دسترسی برای برقراری تماس با API Nest استفاده کند.

جریان OAuth 2.0
جریان OAuth 2.0

کارهای خود را با مشتری Nest تنظیم کنید

برای یافتن اطلاعات OAuth 2.0 برای مشتری خود ، برگه نمای کلی صفحه مشتری را بررسی کنید.

URI یا مجوز مبتنی بر PIN تغییر مسیر دهید؟

هنگامی که مشتری خود را پیکربندی می کنید ، از شما خواسته می شود یک URI تغییر مسیر را وارد کنید یا زمینه های URI تغییر مسیر را خالی بگذارید تا از مجوزهای مبتنی بر PIN استفاده کنید.

اگر محصول شما وسیله ای است که دارای برنامه یا صفحه وب مرتبط نیست (به عنوان مثال ، یک ردیاب تناسب اندام ، یک دستگاه یا پانل امنیتی) ، قسمتهای Redirect URI را خالی بگذارید.

اگر محصول شما یک مؤلفه مرورگر دارد ، بهترین کار این است که URI را تغییر مسیر دهید.

درخواست مجوز

پیکربندی مشتری شامل مجموعه ای از مجوزها (همچنین نامیده می شود اسکوپ) است. اجازه یک پارامتر متغیر است که مجموعه ای از منابع و عملیاتی را که یک نشانه دسترسی به آنها اجازه می دهد کنترل می کند. معمولاً بهترین روش برای درخواست مجوزها به صورت تدریجی ، در زمان نیاز به دسترسی است ، نه از جلو.

نتیجه

هنگامی که پیکربندی را ذخیره می کنید ، به مشتری شما شناسه منحصر به فرد Client و Client Secret اختصاص داده می شود. علاوه بر این ، به مشتری شما یک URL مجوز اختصاص داده می شود.

URL مجوز شامل یک پارامتر دولتی است که می توانید برای تست حملات احتمالی جعل درخواست درخواست بین سایت (CSRF) استفاده کنید. به آزمایش حملات CSRF مراجعه کنید.

جزئیات OAuth

درخواست کد مجوز کنید

پس از پیکربندی مشتری خود ، می توانید کد مجوز (گاهی اوقات کد PIN خوانده می شود) را درخواست کنید. کد مجوز نشانه نهایی نیست که شما برای برقراری تماس با Nest استفاده می کنید. در مرحله بعدی جریان OAuth 2.0 برای تبادل یک نشانه دسترسی واقعی استفاده می شود. در این مرحله اطمینان مستقیم از Nest برای کاربر فراهم می شود که اجازه دسترسی به محصول صحیح و دسترسی توافق شده را داده است.

تجربه کاربر

یک صفحه Works with Nest ارائه می دهیم که از کاربر می خواهد دسترسی به محصول شما داشته باشد. این محصول شما را مشخص می کند و مجوزهای خاص کاربر (اسکوپ) که محصول شما درخواست کرده است را مشخص می کند. کلمات روی صفحه از پیکربندی مشتری شما آمده است.

برای آزمایش این خود ، URL مجوز را از مرحله 1 در یک مرورگر بارگذاری کنید. شما باید صفحه درخواست دسترسی به آشیانه را مشاهده کنید:

با لانه کار می کند

پیش بروید و روی [ACCEPT] خود کلیک کنید تا آنچه کاربر می بیند را ببینید. با کلیک کردن بر روی دکمه [ACCEPT] ، کاربر درخواست محصول شما را برای دسترسی به داده های خود تأیید می کند.

تجربه PIN

اگر قسمتهای Redirect URI را در پیکربندی مشتری خالی بگذارید ، کاربر به صفحه Nest (پستی) (کد مجوز) نمایش داده می شود. UI دستگاه شما پس از آن باید کاربر را به صورت دستی وارد پین کند.

Pincode

تغییر تجربه URI

اگر یک URI تغییر مسیر را در پیکربندی مشتری خود وارد کنید ، کاربر به صفحه ای در ابر شما (یا localhost) هدایت می شود ، و Nest به طور خودکار کد مجوز را به دستگاه کاربر ارسال می کند.

برای حملات CSRF تست کنید

قبل از پذیرش کد مجوز ، محصول شما باید اطمینان حاصل کند که مقدار برگشتی در پارامتر حالت با مقدار دولت از درخواست مجوز اصلی شما مطابقت دارد. این تضمین می کند که شما با کاربر واقعی سر و کار دارید و نه یک اسکریپت مخرب. اگر مقادیر حالت مطابقت ندارند ، باید یک کد خطای HTTP غیر مجاز 401 را در پاسخ پرتاب کنید.

حمله CSRF حمله ای است که کاربر نهایی را مجبور می کند اقدامات ناخواسته را بر روی یک برنامه وب که در آن در حال حاضر تأیید شده است ، انجام دهد.

حمله CSRF
حمله CSRF

برای کمک به جلوگیری از حملات CSRF ، توصیه می کنیم هنگام درخواست مجوز ، همیشه state غیر قابل تحمل را ارائه دهید.

به این ترتیب ، آثار شما با یکپارچه سازی 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) ، base-64 آن را رمزگذاری کرده و آن را به عنوان یک پارامتر حالت به ابر Nest (انتقال) انتقال دهید.

در اینجا یک مثال پایتون وجود دارد که از 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)
 

پیام های خطای کد مجوز

اگر درخواست کد مجوز انجام نشد ، کاربران پیام خطایی را مشاهده می کنند. برای اطلاعات بیشتر در مورد این پیام ها و نحوه جلوگیری از آنها ، به مرجع مجوز مراجعه کنید .

کد مجوز مبادله برای یک نشانه دسترسی

آخرین مرحله برای بدست آوردن یک نشانه دسترسی این است که کالای شما با استفاده از کد مجوز قبلاً خریداری شده ، درخواست یکی کند. این کار با انجام درخواست HTTP POST "x-www-form-urlencoded" انجام می شود.

پارامترهای زیر را در درخواست وارد کنید. هر چهار پارامتر مورد نیاز است.

پارامتر شرح
شناسه مشتری شناسه مشتری در مرحله 1
مشتری_سکرت راز مشتری در مرحله 1
کد کد مجوز دریافت شده در مرحله 2
grant_type مقدار این قسمت همیشه باید باشد: authorization_code

قبل از هر تماس POST ، یک کد مجوز جدید دریافت کنید. برای این کار ، URL مجوز خود را بارگیری کنید. سپس پارامتر code POST را تغییر دهید تا code مجوز جدید در آن وارد شود.

نمونه کد (نویسنده)

نمونه ها را به زبان های مختلف مشاهده کنید .

مثال پستچی (نویسنده)

Postman روشی آسان برای آزمایش درخواستهای OAuth فراهم می کند.

در برگه Headers ، مطمئن شوید که Content-Type = application/x-www-form-urlencoded .

برای دستیابی به نشانه دسترسی ، هدر POST را می دهید

در زبانه بدن ، کلید زیر را وارد کنید: جفت ارزش.

بدنه POST برای دریافت نشانه دسترسی

به پاسخ به نشانه دسترسی پیدا کنید

یک درخواست موفقیت آمیز یک شیء JSON را شامل می شود که شامل زمینه های زیر است:

  • access_token - نشانه دسترسی برای کاربر. این مقدار باید ایمن باشد.
  • expires_in - قبل از انقضا توکن ، تعداد ثانیه از زمان درخواست آن باقی مانده است.

به پیام های خطای توکن دسترسی پیدا کنید

در صورت عدم موفقیت درخواست ، خطایی در قالب کد وضعیت HTTP دریافت می کنید. برای کسب اطلاعات بیشتر در مورد این خطاها و نحوه جلوگیری از آنها ، به مرجع مجوز مراجعه کنید .

درخواست های معتبر را انجام دهید

بعد از اینکه یک محصول دسترسی به نشانه دسترسی پیدا کرد ، آن را به عنوان API Nest در یک هدر اجازه HTTP ارسال می کند. ارسال نشانه ها به عنوان پارامترهای رشته پرسش و پاسخ URI امکان پذیر است ، اما ما آن را توصیه نمی کنیم ، زیرا پارامترهای URI می توانند در پرونده های log که کاملاً ایمن نیستند به پایان برسند.

نشانه های دسترسی فقط برای مجموعه عملیات و منابع توصیف شده در دامنه درخواست توکن معتبر هستند. به عنوان مثال ، اگر یک نشانه دسترسی برای API Nest Therostat صادر شده باشد ، به API Nest Camera اجازه دسترسی نمی دهد.

نمونه کد (خواندن / نوشتن)

مثال پستچی (خواندن / نوشتن)

Postman روشی آسان برای آزمایش تماس های API با استفاده از Content-Type = application/json فراهم می کند.

برای خواندن اطلاعات آماده شوید

نشانه های نامعتبر است

اگر با استفاده از یک نشانه نامعتبر تماس API برقرار کنید ، یک پاسخ 401 غیر مجاز از سرور دریافت می کنید. یک نشانه می تواند نامعتبر و نیاز به بازسازی داشته باشد زیرا:

  • منقضی شده است
  • کاربر مجوزی را که در ابتدا به محصول شما داده اند ابطال کرده است

مهم است که محصول خود را کپی کنید تا به درستی با یک خطای 401 غیرمجاز از طریق تغییر مسیر کاربر به سمت شروع گردش کار مجوز ، به درستی عمل کند.

با اتصال لانه بسته می شود

اگر یک کاربر اتصال با Nest را حذف کند ، محصول شما یک رویداد auth_revoked را دریافت می کند و اتصال بسته می شود.