Google致力于提高黑人社区的种族平等。 怎么看。
此页面由 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事件,并且连接会关闭。