此页面由 Cloud Translation API 翻译。

适用于电视和受限输入设备应用的 OAuth 2.0

。

本文档将介绍如何实现 OAuth 2.0 授权，以便通过在电视、游戏机和打印机等设备上运行的应用访问 Google API。更具体地说，此流程专为无法访问浏览器或输入功能有限的设备而设计。

OAuth 2.0 可让用户与应用共享特定数据，同时保持其用户名、密码和其他信息的私密性。例如，TV 应用可以使用 OAuth 2.0 获取选择存储在 Google 云端硬盘中的文件的权限。

由于使用此流程的应用分发到各个设备，因此系统会假定这些应用无法保密。当用户出现在应用或应用在后台运行时，他们可以访问 Google API。

替代方案

如果您要为 Android、iOS、macOS、Linux 或 Windows（包括 Universal 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。
选择 TV 和受限输入设备应用类型。
为您的 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 向用户显示的同意屏幕。如需了解已安装的应用或设备，请参阅允许的范围列表。通过范围，您的应用只能请求访问所需的资源，同时还能控制用户向应用授予的访问权限。因此，请求的范围数量与征得用户同意的可能性之间存在相反关系。

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。

设计界面时，请遵循以下规则：

user_code
- user_code 必须显示在可以处理 15 个“W”大小字符的字段中。换言之，如果您可以正确显示代码 WWWWWWWWWWWWWWW，则说明界面有效，建议您在测试 user_code 的界面显示方式时使用该字符串值。
- user_code 区分大小写，请勿以任何方式进行修改，例如更改大小写或插入其他格式字符。
verification_url
- 您显示 verification_url 的空间必须足够宽，可以处理长度为 40 个字符的网址字符串。
- 除了用于移除要显示的架构之外，您不应以任何方式修改 verification_url。如果您确实要出于显示原因从网址中去除架构（例如 https://），请确保您的应用可以同时处理 http 和 https 变体。

警告：这些值随时都可能会发生更改，您不应在代码中对任一值进行硬编码。同样，除了选择性地从 verification_url 中移除架构之外，您不应以任何其他方式修改这些值。

第 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，在登录 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 客户端。例如，如果 `client_id` 参数值无效，便会发生此错误。 OAuth 客户端类型不正确。确保客户端 ID 的应用类型设置为电视和受限输入设备。
`invalid_grant`	`400`	`code` 参数值无效，已声明或无法解析。
`unsupported_grant_type`	`400`	`grant_type` 参数值无效。
`org_internal`	`403`	请求中的 OAuth 客户端 ID 属于项目，该项目限制了对特定 Google Cloud 组织中的 Google 帐号的访问。确认您的 OAuth 应用的用户类型配置。

调用 Google API

在您的应用获得访问令牌后，您可以根据该 API 所需的访问权限范围，使用该令牌代表用户帐号调用 Google 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

以下是经过身份验证的用户的使用 access_token 查询字符串参数的同一 API：

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 流程：

email
openid
profile

Drive API

https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.file

YouTube API

https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.readonly

适用于电视和受限输入设备应用的 OAuth 2.0

前提条件

为您的项目启用 API

创建授权凭据

确定访问权限范围

获取 OAuth 2.0 访问令牌

第 1 步：请求设备和用户代码

示例

第 2 步：处理授权服务器响应

成功响应

“已超出配额”响应

第 3 步：显示用户代码

第 4 步：轮询 Google 的授权服务器

示例

第 5 步：用户响应访问权限请求

第 6 步：处理轮询请求的响应

已授予权限

访问遭拒

待授权

轮询频率过高

其他错误

调用 Google API

HTTP GET 示例

curl 示例

刷新访问令牌

撤消令牌

允许的范围

OpenID Connect、Google 登录

Drive API

YouTube API

`curl` 示例