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

- - -

本文介绍了如何实现 OAuth 2.0 授权,以便通过电视、游戏机、打印机等设备上运行的应用访问 YouTube Data 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,请按以下步骤操作:

  1. Open the API Library (在 Google API Console中)。
  2. If prompted, select a project, or create a new one.
  3. 使用“库”页面查找并启用 YouTube Data API。查找您的应用将使用的任何其他 API,并启用它们。

创建授权凭据

任何使用 OAuth 2.0 访问 Google API 的应用都必须具有授权凭据,用于向 Google 的 OAuth 2.0 服务器标识应用。以下步骤说明了如何为项目创建凭据。然后,您的应用就可以使用这些凭据访问已为该项目启用的 API。

  1. Go to the Credentials page.
  2. 依次点击创建凭据 > OAuth 客户端 ID
  3. 选择 TVs and Limited Input devices 应用类型。
  4. 为您的 OAuth 2.0 客户端命名,然后点击创建

确定访问权限范围

借助范围,您的应用可以仅请求访问所需的资源,同时还能让用户控制他们向您的应用授予的访问权限大小。因此,请求的范围数量与征得用户同意的可能性之间可能存在反向关系。

在开始实现 OAuth 2.0 授权之前,我们建议您先确定您的应用需要访问权限的范围。

YouTube Data API v3 使用以下范围:

瞄准镜
https://www.googleapis.com/auth/youtube管理您的 YouTube 帐号
https://www.googleapis.com/auth/youtube.channel-memberships.creator查看包含以下信息的列表:当前活跃的频道会员、其当前级别以及其成为会员的时间
https://www.googleapis.com/auth/youtube.force-ssl查看、修改以及永久删除您的 YouTube 视频、评分、评论和字幕
https://www.googleapis.com/auth/youtube.readonly查看您的 YouTube 帐号
https://www.googleapis.com/auth/youtube.upload管理您的 YouTube 视频
https://www.googleapis.com/auth/youtubepartner查看和管理您在 YouTube 上的资源和关联内容
https://www.googleapis.com/auth/youtubepartner-channel-audit查看您的 YouTube 频道中关于 YouTube 合作伙伴试演的隐私信息

如需了解已安装的应用或设备,请参阅允许的范围列表。

获取 OAuth 2.0 访问令牌

即使您的应用在输入功能有限的设备上运行,用户也必须单独访问具有更丰富输入功能的设备,才能完成此授权流程。该流程包含以下步骤:

  1. 您的应用向 Google 的授权服务器发送请求,用于标识您的应用将请求访问的权限的范围。
  2. 服务器会返回后续步骤中使用的一些信息,如设备代码和用户代码。
  3. 您可以显示信息,供用户在单独的设备上输入以对应用进行授权。
  4. 您的应用开始轮询 Google 的授权服务器,以确定用户是否已向您的应用授权。
  5. 用户切换到具有更丰富输入功能的设备,启动网络浏览器,转到第 3 步中显示的网址,并输入第 3 步中显示的代码。然后,用户可以授予(或拒绝)对您的应用的访问权限。
  6. 对轮询请求的下一个响应中包含您的应用代表用户向请求授权所需的令牌。(如果用户拒绝访问您的应用,则响应将不包含令牌。)

下图说明了此过程:

用户在装有浏览器的单独设备上登录

以下部分详细介绍了这些步骤。鉴于设备可能具有的功能和运行时环境的范围,本文档中显示的示例使用 curl 命令行实用程序。这些示例应易于移植到各种语言和运行时。

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

在此步骤中,您的设备会向 Google 的授权服务器 (https://oauth2.googleapis.com/device/code) 发送一个 HTTP POST 请求,该请求用于标识您的应用,以及该应用要代表用户访问的访问权限范围。 您应该使用 device_authorization_endpoint 元数据值从发现文档中检索此网址。添加以下 HTTP 请求参数:

参数
client_id 必需

您的应用的客户端 ID。您可以在 API Console Credentials page中找到此值。

scope 必需

用空格分隔的范围列表,用于标识您的应用可以代表用户访问的资源。这些值会告知 Google 向用户显示的同意屏幕。如需了解已安装的应用或设备,请参阅允许的范围列表。

范围可让您的应用仅请求访问所需的资源,同时还使用户能够控制他们向您的应用授予的访问权限大小。因此,请求的范围数量与征得用户同意的可能性之间存在反向关系。

YouTube Data API v3 使用以下范围:

瞄准镜
https://www.googleapis.com/auth/youtube管理您的 YouTube 帐号
https://www.googleapis.com/auth/youtube.channel-memberships.creator查看包含以下信息的列表:当前活跃的频道会员、其当前级别以及其成为会员的时间
https://www.googleapis.com/auth/youtube.force-ssl查看、修改以及永久删除您的 YouTube 视频、评分、评论和字幕
https://www.googleapis.com/auth/youtube.readonly查看您的 YouTube 帐号
https://www.googleapis.com/auth/youtube.upload管理您的 YouTube 视频
https://www.googleapis.com/auth/youtubepartner查看和管理您在 YouTube 上的资源和关联内容
https://www.googleapis.com/auth/youtubepartner-channel-audit查看您的 YouTube 频道中关于 YouTube 合作伙伴试演的隐私信息

OAuth 2.0 API 范围文档提供了可用于访问 Google API 的范围的完整列表。

示例

以下代码段展示了一个示例请求:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

以下示例展示了用于发送同一请求的 curl 命令:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

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

授权服务器会返回以下响应之一:

成功响应

如果请求有效,则响应将是一个包含以下属性的 JSON 对象:

属性
device_code Google 分配的一个独一无二的值,用于标识运行请求授权的应用的设备。用户将通过输入功能更丰富的另一部设备向该设备授权。例如,用户可以使用笔记本电脑或手机向在电视上运行的应用授权。在这种情况下,device_code 会标识电视。

此代码可让运行应用的设备安全地确定用户是授予还是拒绝了访问权限。

expires_in device_codeuser_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_urluser_code。两个值都可以包含 US-ASCII 字符集中的任何可打印字符。您向用户显示的内容应指示用户在单独的设备上导航到 verification_url,然后输入 user_code

在设计界面 (UI) 时,请遵循以下规则:

  • user_code
    • user_code 必须显示在可以处理大小为 15“W”的字符的字段中。也就是说,如果您可以正确显示代码 WWWWWWWWWWWWWWW,表示您的界面是有效的,我们建议在测试 user_code 在界面中的显示方式时使用该字符串值。
    • user_code 区分大小写,且不应以任何方式修改,例如更改大小写或插入其他格式字符。
  • verification_url
    • 显示 verification_url 的空间必须足够宽,可处理长度为 40 个字符的网址字符串。
    • 您不得以任何方式修改 verification_url,只能选择性地移除要显示的架构。如果您确实出于显示原因打算去掉网址中的架构(例如 https://),请确保您的应用可以同时处理 httphttps 变体。

第 4 步:向 Google 的授权服务器进行轮询

由于用户将使用单独的设备导航到 verification_url 并授予(或拒绝)访问权限,因此当用户响应访问权限请求时,系统不会自动通知发出请求的设备。因此,发出请求的设备需要轮询 Google 的授权服务器,以确定用户何时响应请求。

发出请求的设备应继续发送轮询请求,直到收到表明用户已响应访问请求的响应,或者 第 2 步中获得的 device_codeuser_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 客户端。例如,如果 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

在您的应用获得访问令牌后,如果已授予 Google API 所需的访问权限范围,您就可以使用令牌代表指定用户账号调用该 API。为此,请通过加入 access_token 查询参数或 Authorization HTTP 标头 Bearer 值,将访问令牌添加到对 API 的请求中。请尽可能使用 HTTP 标头,因为查询字符串往往会显示在服务器日志中。在大多数情况下,您可以使用客户端库来设置对 Google API 的调用(例如,调用 YouTube Live Streaming API 时)。

请注意,YouTube Live Streaming API 不支持服务帐号流程。由于无法将服务账号与 YouTube 账号相关联,因此尝试使用此流程对请求授权将产生 NoLinkedYouTubeAccount 错误。

您可以在 OAuth 2.0 Playground 中试用所有 Google API 并查看其范围。

HTTP GET 示例

使用 Authorization: Bearer HTTP 标头对 liveBroadcasts.list 端点 (YouTube Live Streaming API) 的调用可能如下所示。请注意,您需要指定自己的访问令牌:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

以下是使用 access_token 查询字符串参数对已通过身份验证的用户的同一 API 的调用:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl 示例

您可以使用 curl 命令行应用测试这些命令。以下是使用 HTTP 标头选项(首选)的示例:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

或者,也可以使用查询字符串参数选项:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

刷新访问令牌

访问令牌会定期过期,并成为相关 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 ConnectGoogle 登录

  • 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