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訪問權限的訪問令牌。單個訪問令牌可以授予對API多個部分的不同程度的訪問權限。

當您的產品將瀏覽器重定向到帶有查詢參數(指示所請求的訪問權限)的Nest URL時,授權序列開始。 Nest處理用戶身份驗證,會話選擇和用戶同意。結果是授權碼,您的產品可以使用該授權碼交換訪問令牌。然後,您的產品可以使用訪問令牌來調用Nest API。

OAuth 2.0流程
OAuth 2.0流程

使用Nest客戶端配置Works

要查找您的客戶端的OAuth 2.0憑據,請檢查客戶端頁面的概述標籤。

重定向基於URI或PIN的授權?

在配置客戶端時,系統會提示您輸入重定向URI或將重定向URI字段留空以使用基於PIN的授權。

如果您的產品是沒有相關應用程序或網頁的設備(例如,健身追踪器,設備或安全面板),請將“重定向URI”字段保留為空白。

如果您的產品具有瀏覽器組件,則最佳做法是包括重定向URI。

請求權限

客戶端配置包括一組權限(也稱為作用域)。權限是一個可變參數,用於控制訪問令牌允許的資源和操作的集合。通常,最佳做法是在需要訪問時而不是預先訪問,以遞增方式請求權限。

結果

保存配置時,將為客戶端分配唯一的客戶端ID和客戶端密鑰。此外,還會為您的客戶分配一個授權URL。

授權URL包含一個狀態參數,可用於測試可能的跨站點請求偽造(CSRF)攻擊。請參閱測試CSRF攻擊

OAuth詳細信息

索取授權碼

配置客戶端后,您可以請求授權碼(有時稱為PIN碼)。授權代碼不是您用來調用Nest的最終令牌。 OAuth 2.0流程的下一步中將使用它來交換實際的訪問令牌。此步驟可直接從Nest向用戶提供保證,即可以通過同意的訪問權限授予正確產品的權限。

用戶體驗

我們提供了“帶有嵌套的作品”頁面,要求用戶授予對您產品的訪問權限。這將標識您的產品,並概述產品已請求的特定用戶權限(範圍)。屏幕上的文字來自您的客戶端配置。

要自己進行測試,請將步驟1中的授權URL加載到瀏覽器中。您應該看到一個帶有Nest的訪問請求頁面:

與Nest搭配使用

繼續並自己單擊[接受]以查看用戶看到的內容。通過單擊[ACCEPT]按鈕,用戶正在批准您的產品訪問其數據的請求。

PIN經驗

如果您在客戶端配置中將“重定向URI”字段保留為空白,則會將用戶重定向到顯示PIN(授權碼)的Nest頁面。然後,您的設備用戶界面應提示用戶手動輸入PIN。

PIN碼

重定向URI體驗

如果您在客戶端配置中包含重定向URI,則會將用戶重定向到您的雲(或本地主機)中的頁面,並且Nest會自動將授權代碼發送到用戶的設備。

測試CSRF攻擊

在接受授權碼之前,您的產品應確保state參數中返回的值與原始授權請求中的狀態值匹配。這樣可以確保您與實際用戶打交道,而不是惡意腳本。如果狀態值不匹配,您應該拋出401未經授權的HTTP錯誤代碼作為響應。

CSRF攻擊是一種攻擊,它迫使最終用戶在當前經過身份驗證的Web應用程序上執行不需要的操作。

CSRF攻擊
CSRF攻擊

為了幫助防止CSRF攻擊,我們建議您在請求授權時始終提交不可猜測的state

這樣,您的與Nest集成的作品可以驗證從Nest雲獲得的訪問代碼是否響應您的產品而不是某些其他產品的請求。

例:

假設在您的客戶端配置中,您指定了重定向URI:

 http://localhost:5000/callback
 

假設您的客戶端在授權URL中發送了7tvPJiv8StrAqo9IQE9xsJaDso4狀態:

 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 -
 

您的產品會收到此狀態值,並且應該對其進行編程以僅接受具有可驗證狀態的重定向。

有多種方法可以生成不可猜測的狀態參數。您可以從內存中保存的字典中提供隨機狀態值或可重新計算的值。您可以將私鑰與一些易於驗證的變量(例如,客戶端ID和會話cookie)一起使用,以計算哈希值。如果沒有私鑰,這將導致難以猜測的字節值。另一個建議是散列當前日期和時間。使用這種方法,您的應用程序必須節省傳輸時間以進行驗證或允許有效期的滑動(例如,使用基於時間的一次性密碼算法[TOTP])。

計算出密鑰哈希消息認證代碼(HMAC)之後,base-64對其進行編碼,並將其作為狀態參數傳遞給Nest雲。

這是一個使用datetime的Python示例:

 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)
 

授權碼錯誤消息

如果授權碼請求失敗,則用戶會看到錯誤消息。有關這些消息以及如何防止它們的更多信息,請參閱《 授權參考》

交換訪問令牌的授權代碼

獲取訪問令牌的最後一步是讓您的產品使用剛剛獲取的授權碼來請求一個。這是通過發出“ x-www-form-urlencoded” HTTP POST請求來完成的。

在請求中包括以下參數。所有四個參數都是必需的。

參數描述
client_id 步驟1中的客戶端ID
client_secret 步驟1中的客戶機密
步驟2中收到的授權碼
grant_type 該字段的值應始終為: authorization_code

在每個POST調用之前,獲取一個新的授權碼。為此,請重新加載您的授權URL。然後更改POST的code參數以包括新的授權代碼。

代碼示例(身份驗證)

查看各種語言的示例

郵遞員示例(auth)

郵遞員提供了一種測試OAuth請求的簡便方法。

標題選項卡上,確保Content-Type = application/x-www-form-urlencoded

POST標頭以獲取訪問令牌

在“ 正文”選項卡上,包括以下key:value對。

POST正文以獲取訪問令牌

訪問令牌響應

成功的請求將返回一個JSON對象,其中包含以下字段:

  • access_token —用戶的訪問令牌。此值必須保持安全。
  • expires_in —從請求令牌到令牌過期,剩餘的秒數。

訪問令牌錯誤消息

如果請求失敗,您將收到HTTP狀態代碼形式的錯誤。有關這些錯誤以及如何防止它們的更多信息,請參閱授權參考

發出驗證請求

產品獲得訪問令牌後,它將令牌發送到HTTP授權標頭中的Nest API。可以將令牌作為URI查詢字符串參數發送,但我們不建議這樣做,因為URI參數可能最終存儲在不完全安全的日誌文件中。

訪問令牌僅對令牌請求範圍內所述的一組操作和資源有效。例如,如果為Nest Thermostat API頒發了訪問令牌,則它不會授予對Nest Camera API的訪問權限。

代碼示例(讀/寫)

郵遞員示例(讀/寫)

Postman提供了一種使用Content-Type = application/json測試API調用的簡便方法。

獲取讀取數據

無效的令牌

如果使用無效令牌進行API調用,則會從服務器返回401未經授權的響應。令牌可能無效,需要重新生成,因為:

  • 已經過期
  • 用戶已撤銷最初授予您產品的權限

通過對用戶進行重定向以將其重定向回到授權工作流的開始,對產品進行編碼以正確處理401未經授權的錯誤非常重要。

在Nest連接關閉的情況下工作

如果用戶刪除了Works with Nest連接 ,則您的產品會收到auth_revoked事件,並且連接會關閉。