本文档介绍了如何实现 OAuth 2.0 授权，以通过在电视、游戏机和打印机等设备上运行的应用访问 Google API。更具体地说，此流程是针对无法访问浏览器或输入功能受限的设备设计的。
OAuth 2.0 可让用户与应用共享特定数据，同时保持其用户名、密码和其他信息的私密性。例如，TV 应用可以使用 OAuth 2.0 来获取选择 Google 云端硬盘中存储的文件的权限。
由于使用此流程的应用分发到各个设备，因此系统假定应用无法保密。当用户位于应用中或应用在后台运行时，他们可以访问 Google API。
替代方案
如果您要为 Android、iOS、macOS、Linux 或 Windows（包括通用 Windows 平台）等平台编写应用，并且该平台可以使用浏览器和完整的输入功能，请使用适用于移动设备和桌面应用的 OAuth 2.0 流程。（即使您的应用是没有图形界面的命令行工具，也应使用该流程。）
如果您只想让用户使用他们的 Google 帐号登录，并使用 JWT ID 令牌获取基本的用户个人资料信息，请参阅在电视和受限输入设备上登录。
前提条件
为您的项目启用 API
调用 Google API 的任何应用都需要在 API Console中启用这些 API。
如需为您的项目启用该 API，请按以下步骤操作：
- Open the API Library （位于 Google API Console中）。
- If prompted, select a project, or create a new one.
- API Library 列出了所有可用的 API（按产品系列和热门程度分组）。如果列表中没有显示您要启用的 API，请使用搜索功能查找该 API，或点击其所属产品系列中的查看全部。
- 选择您要启用的 API，然后点击启用按钮。
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
创建授权凭据
任何使用 OAuth 2.0 访问 Google API 的应用都必须具有授权凭据，以便向 Google 的 OAuth 2.0 服务器表明应用的身份。以下步骤说明了如何为项目创建凭据。然后，您的应用可以使用这些凭据访问您已为该项目启用的 API。
- Go to the Credentials page.
- 依次点击创建凭据 > OAuth 客户端 ID。
- 选择 TVs and Limited Input devices 应用类型。
- 为您的 OAuth 2.0 客户端命名，然后点击创建。
确定访问权限范围
范围可让您的应用仅请求访问所需资源，同时还可让用户控制他们向您的应用授予的访问权限量。因此，请求的范围数量与征得用户同意的可能性之间可能呈反向关系。
在开始实现 OAuth 2.0 授权之前，我们建议您确定您的应用需要访问权限的范围。
请参阅已安装的应用或设备的允许的范围列表。
获取 OAuth 2.0 访问令牌
即使您的应用在输入功能有限的设备上运行，用户也必须能够单独访问具备更丰富输入功能的设备，才能完成此授权流程。 该流程包含以下步骤：
- 您的应用向 Google 的授权服务器发送请求，用于标识该应用将请求访问的权限的范围。
- 服务器会使用后续步骤中用到的一些信息（如设备代码和用户代码）进行响应。
- 您可以显示用户可在单独的设备上输入的信息，以便向您的应用授权。
- 您的应用开始轮询 Google 的授权服务器，以确定用户是否已授权您的应用。
- 用户切换到具备更丰富输入功能的设备，启动网络浏览器，前往第 3 步中显示的网址，并输入同样在第 3 步中显示的代码。然后，用户可以授予（或拒绝）对您的应用的访问权限。
- 对轮询请求的下一个响应中包含您的应用代表用户为请求授权所需的令牌。（如果用户拒绝访问您的应用，则响应中将不会包含令牌。）
下图说明了此过程：
下面几部分将详细介绍这些步骤。鉴于设备可能具有的功能和运行时环境的范围，本文档中显示的示例使用 curl 命令行实用程序。这些示例应易于移植到各种语言和运行时。
第 1 步：请求获取设备和用户验证码
在此步骤中，您的设备会向 Google 的授权服务器 (https://oauth2.googleapis.com/device/code) 发送 HTTP POST 请求，以标识您的应用以及该应用要代表用户访问的访问权限范围。您应使用 device_authorization_endpoint 元数据值从发现文档中检索此网址。包括以下 HTTP 请求参数：
| 参数 | |
|---|---|
client_id |
必需
您的应用的客户端 ID。您可以在 API Console Credentials page中找到此值。 |
scope |
必需
以空格分隔的范围列表，用于标识您的应用可以代表用户访问的资源。这些值会告知 Google 向用户显示的权限请求页面。请参阅已安装的应用或设备的允许的范围列表。 范围可让您的应用仅请求访问所需资源，同时还允许用户控制他们向您的应用授予的访问权限大小。因此，请求的范围数量与征得用户同意的可能性之间存在反向关系。 |
示例
以下代码段展示了一个示例请求：
POST /device/code HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id&scope=email%20profile
以下示例展示了用于发送同一请求的 curl 命令：
curl -d "client_id=client_id&scope=email%20profile" \
https://oauth2.googleapis.com/device/code
第 2 步：处理授权服务器响应
授权服务器会返回以下响应之一：
成功响应
如果请求有效，则您的响应将是一个包含以下属性的 JSON 对象：
| 属性 | |
|---|---|
device_code |
Google 分配的值，用于识别运行请求授权的应用的设备。用户将通过输入功能更丰富的另一部设备向该设备授权。例如，用户可能会使用笔记本电脑或手机向在电视上运行的应用授权。在这种情况下，device_code 会标识电视。
此代码可让运行应用的设备安全地确定用户是授予还是拒绝了访问权限。 |
expires_in |
device_code 和 user_code 的有效时长（以秒为单位）。如果此时用户未完成授权流程，且您的设备也未轮询以检索有关用户决策的信息，您可能需要从第 1 步重新开始此过程。 |
interval |
两次轮询请求之间设备应等待的时长（以秒为单位）。例如，如果值为 5，您的设备应每 5 秒向 Google 的授权服务器发送一个轮询请求。如需了解详情，请参阅第 3 步。 |
user_code |
区分大小写的值，向 Google 标识应用请求访问的范围。您的界面将指示用户在一部具有更丰富输入功能的单独设备上输入此值。然后，在提示用户授予对应用的访问权限时，Google 会使用该值显示一组正确的范围。 |
verification_url |
用户必须在另一台设备上导航到的网址，才能输入 user_code 并授予或拒绝对您的应用的访问权限。您的界面也会显示此值。 |
以下代码段显示了一个示例响应：
{
"device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
"user_code": "GQVQ-JKEC",
"verification_url": "https://www.google.com/device",
"expires_in": 1800,
"interval": 5
}
“已超出配额”响应
如果您的设备代码请求超出了与您的客户端 ID 关联的配额，您将收到 403 响应，其中包含以下错误：
{
"error_code": "rate_limit_exceeded"
}
在这种情况下，请使用退避算法策略来降低请求速率。
第 3 步：显示用户代码
向用户显示第 2 步中获得的 verification_url 和 user_code。这两个值都可以包含 US-ASCII 字符集中的任何可打印字符。您向用户显示的内容应指示用户在单独的设备上转到 verification_url 并输入 user_code。
设计界面 (UI) 时应遵循以下规则：
user_codeuser_code必须显示在可处理大小为 15“W”字符的字段中。也就是说，如果您可以正确显示代码WWWWWWWWWWWWWWW，则表示界面有效，因此，我们建议您在测试user_code在界面中的显示方式时使用该字符串值。user_code区分大小写，并且不得进行任何修改，例如更改大小写或插入其他格式字符。
verification_url- 显示
verification_url的空间必须足够宽，可以处理长度为 40 个字符的网址字符串。 - 除非视需要移除用于显示的架构，否则不得以任何方式修改
verification_url。如果您打算出于显示原因去掉网址中的架构（例如https://），请确保您的应用可以同时处理http和https变体。
- 显示
第 4 步：轮询 Google 的授权服务器
由于用户将使用单独的设备导航到 verification_url 并授予（或拒绝）访问权限，因此当用户响应访问请求时，系统不会自动通知发起请求的设备。因此，发出请求的设备需要轮询 Google 的授权服务器，以确定用户何时响应请求。
发出请求的设备应继续发送轮询请求，直到收到表明用户已响应访问请求的响应，或者直到
第 2 步中获得的 device_code 和 user_code 到期。第 2 步中返回的 interval 用于指定两次请求之间等待的时长（以秒为单位）。
要轮询的端点的网址为 https://oauth2.googleapis.com/token。轮询请求包含以下参数：
| 参数 | |
|---|---|
client_id |
您的应用的客户端 ID。您可以在 API Console Credentials page中找到此值。 |
client_secret |
提供的 client_id 的客户端密钥。您可以在 API Console
Credentials page中找到此值。 |
device_code |
授权服务器在第 2 步中返回的 device_code。 |
grant_type |
将此值设置为 urn:ietf:params:oauth:grant-type:device_code。 |
示例
以下代码段展示了一个示例请求：
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id& client_secret=client_secret& device_code=device_code& grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
以下示例展示了用于发送同一请求的 curl 命令：
curl -d "client_id=client_id&client_secret=client_secret& \
device_code=device_code& \
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/token
第 5 步：用户回复访问权限请求
下图显示了一个页面，类似于用户导航到第 3 步中显示的 verification_url 时看到的页面：
输入 user_code 后，如果用户尚未登录并登录 Google，则会看到如下所示的同意屏幕：
第 6 步：处理对轮询请求的响应
Google 的授权服务器会使用以下响应之一来响应每个轮询请求：
已授予权限
如果用户授予了设备访问权限（通过点击同意屏幕上的 Allow），响应中就会包含访问令牌和刷新令牌。这些令牌可让您的设备代表用户访问 Google API。（响应中的 scope 属性决定了设备可以访问哪些 API。）
在这种情况下，API 响应包含以下字段：
| 字段 | |
|---|---|
access_token |
您的应用发送的令牌，用于向 Google API 请求授权。 |
expires_in |
访问令牌的剩余生命周期（以秒为单位）。 |
refresh_token |
可用于获取新访问令牌的令牌。刷新令牌在用户撤消访问权限之前一直有效。 请注意，系统始终会为设备返回刷新令牌。 |
scope |
access_token 授予的访问权限范围，表示为以空格分隔且区分大小写的字符串列表。 |
token_type |
返回的令牌类型。目前，此字段的值始终设置为 Bearer。 |
以下代码段显示了一个示例响应：
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
"token_type": "Bearer",
"refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
访问令牌的生命周期是有限的。如果应用需要长期访问某个 API，则可以使用刷新令牌获取新的访问令牌。如果您的应用需要此类访问权限，则应存储刷新令牌以供日后使用。
访问遭拒
如果用户拒绝授予对设备的访问权限，则服务器响应会出现 403 HTTP 响应状态代码 (Forbidden)。响应包含以下错误：
{
"error": "access_denied",
"error_description": "Forbidden"
}
正在等待授权
如果用户尚未完成授权流程，服务器将返回 428 HTTP 响应状态代码 (Precondition Required)。响应将包含以下错误：
{
"error": "authorization_pending",
"error_description": "Precondition Required"
}
轮询过于频繁
如果设备发送轮询请求的频率过高，则服务器会返回 403 HTTP 响应状态代码 (Forbidden)。响应将包含以下错误：
{
"error": "slow_down",
"error_description": "Forbidden"
}
其他错误
如果轮询请求缺少任何必需参数或参数值不正确，则授权服务器也会返回错误。这些请求通常具有 400 (Bad Request) 或 401 (Unauthorized) HTTP 响应状态代码。这些错误包括：
| 错误 | HTTP 状态代码 | 说明 |
|---|---|---|
admin_policy_enforced |
400 |
根据 Google Workspace 管理员的政策，该 Google 帐号无法对所请求的一个或多个范围进行授权。请参阅 Google Workspace 管理员帮助文章：控制哪些第三方应用和内部应用可以访问 Google Workspace 数据，详细了解在向您的 OAuth 客户端 ID 明确授予访问权限之前，管理员如何限制对范围的访问权限。 |
invalid_client |
401 |
找不到 OAuth 客户端。例如，如果 OAuth 客户端类型不正确。确保将客户端 ID 的应用类型设置为“电视和受限输入设备”。 |
invalid_grant |
400 |
code 参数值无效、已被声明或无法解析。 |
unsupported_grant_type |
400 |
grant_type 参数值无效。 |
org_internal |
403 |
请求中的 OAuth 客户端 ID 属于项目的一部分，用于限制对特定 Google Cloud 组织中的 Google 帐号的访问权限。确认您的 OAuth 应用的用户类型配置。 |
调用 Google API
在您的应用获得访问令牌后，如果已授予 Google API 所需的访问权限范围，您就可以使用该令牌代表指定用户帐号调用该 API。为此，请在向 API 发出的请求中添加访问令牌，方法是加入 access_token 查询参数或 Authorization HTTP 标头 Bearer 值。最好使用 HTTP 标头，因为查询字符串往往会显示在服务器日志中。在大多数情况下，您可以使用客户端库来设置对 Google API 的调用（例如，在调用 Drive Files API 时）。
您可以在 OAuth 2.0 Playground 中试用所有 Google API 并查看其范围。
HTTP GET 示例
使用 Authorization: Bearer HTTP 标头对
drive.files 端点 (Drive Files API) 的调用可能如下所示。请注意，您需要指定自己的访问令牌：
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
以下是针对经过身份验证的用户的同一 API 调用（使用 access_token 查询字符串参数）：
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl 示例
您可以使用 curl 命令行应用测试这些命令。以下是使用 HTTP 标头选项的示例（首选）：
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
或者，也可以使用查询字符串参数选项：
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
刷新访问令牌
访问令牌会定期过期，并成为相关 API 请求的无效凭据。如果您请求离线访问与令牌相关联的范围，则可以刷新访问令牌，而不提示用户授予权限（包括用户不存在时）。
如需刷新访问令牌，您的应用会向 Google 的授权服务器 (https://oauth2.googleapis.com/token) 发送 HTTPS POST 请求，其中包含以下参数：
| 字段 | |
|---|---|
client_id |
从 API Console获得的客户端 ID。 |
client_secret |
从 API Console获得的客户端密钥。 |
grant_type |
根据 OAuth 2.0 规范中的定义，此字段的值必须设置为 refresh_token。 |
refresh_token |
通过授权代码交换返回的刷新令牌。 |
以下代码段展示了一个示例请求：
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
只要用户没有撤消授予应用的访问权限，令牌服务器就会返回一个包含新访问令牌的 JSON 对象。以下代码段显示了一个示例响应：
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
"token_type": "Bearer"
}
请注意，可以发放的刷新令牌的数量是有限制的：每个客户端/用户组合一个限制，另一个限制在所有客户端上每个用户。您应将刷新令牌保存在长期存储中，只要它们仍然有效，请继续使用。如果您的应用请求的刷新令牌过多，可能会达到这些限制，在这种情况下，较旧的刷新令牌将会停止工作。
撤消令牌
在某些情况下，用户可能希望撤消已授予应用的访问权限。用户可以通过访问 帐号设置来撤消访问权限。如需了解详情，请参阅“有权访问您帐号的第三方网站和应用”的“移除网站或应用的访问权限”部分支持文档。
应用也可以通过编程方式撤消已授予其的访问权限。当用户退订、移除应用或应用所需的 API 资源发生显著变化时，程序化撤消就非常重要。换言之，移除流程的一部分可以包含 API 请求，以确保移除之前授予应用的权限。
如需以编程方式撤消令牌，您的应用会向 https://oauth2.googleapis.com/revoke 发出请求，并将该令牌作为参数包含在内：
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}
该令牌可以是访问令牌，也可以是刷新令牌。如果该令牌是访问令牌，并且它具有相应的刷新令牌，则该刷新令牌也会被撤消。
如果撤消处理成功，则响应的 HTTP 状态代码为 200。对于错误情况，系统会返回 HTTP 状态代码 400 以及错误代码。
允许的范围
只有以下范围支持适用于设备的 OAuth 2.0 流程：
OpenID Connect、Google 登录
emailopenidprofile
Drive API
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly