适用于移动应用和桌面应用的 OAuth 2.0

本文档介绍了安装在手机、平板电脑和计算机等设备上的应用如何使用 Google 的 OAuth 2.0 端点来授权访问 YouTube Data API。

OAuth 2.0 可让用户与应用共享特定数据，同时保持其用户名、密码和其他信息的私密性。 例如，应用可以使用 OAuth 2.0 获取向用户 YouTube 频道上传视频的权限。

已安装的应用会分发到各个设备，并且假定这些应用无法保守秘密。它们可以在用户位于应用中时或应用在后台运行时访问 Google API。

此授权流程与用于网络服务器应用的授权流程类似。主要区别在于，已安装的应用必须打开系统浏览器并提供本地重定向 URI，以处理来自 Google 授权服务器的响应。

库和示例

对于移动应用，我们建议使用最新版本的 Google Identity Services 原生库（适用于 Android）和 Google 登录原生库（适用于 iOS）。这些库可处理用户授权，并且比此处描述的较低级别协议更易于实现。

对于在不支持系统浏览器或输入功能有限的设备（例如电视、游戏机、相机或打印机）上运行的应用，请参阅适用于电视和设备的 OAuth 2.0 或在电视和输入受限的设备上登录。

前提条件

为您的项目启用 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，并启用这些 API。

创建授权凭据

任何使用 OAuth 2.0 访问 Google API 的应用都必须具有授权凭据，以向 Google 的 OAuth 2.0 服务器表明应用的身份。以下步骤说明了如何为项目创建凭据。然后，您的应用可以使用这些凭据来访问您为相应项目启用的 API。

1. Go to the Credentials page.
2. 点击创建客户端。
3. 以下部分介绍了 Google 授权服务器支持的客户端类型。选择适合您应用的客户端类型，为 OAuth 客户端命名，并根据需要设置表单中的其他字段。

确定访问权限范围

有了这一范围，您不但可以让应用仅请求访问所需的资源，而且还可以让用户控制其向您的应用授予的访问权限大小。因此，所请求的范围数量与获得用户同意的可能性之间可能存在反比关系。

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

YouTube Data API v3 使用以下范围：

OAuth 2.0 API 范围文档包含您可能用于访问 Google API 的范围的完整列表。

获取 OAuth 2.0 访问令牌

以下步骤展示了您的应用如何与 Google 的 OAuth 2.0 服务器互动，以征得用户同意代表用户执行 API 请求。您的应用必须获得该同意，然后才能执行需要用户授权的 Google API 请求。

第 1 步：生成代码验证器和质询

Google 支持用于代码交换的证明密钥 (PKCE) 协议，以提高已安装应用流程的安全性。系统会为每个授权请求创建一个唯一的代码验证器，并将其转换后的值（称为“code_challenge”）发送到授权服务器以获取授权代码。

创建代码验证器

code_verifier 是一种高熵加密随机字符串，使用非保留字符 [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"，最短长度为 43 个字符，最长长度为 128 个字符。

代码验证器应具有足够的熵，以致无法猜测其值。

创建验证码请求

系统支持通过以下两种方法创建代码质询。

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

第 2 步：向 Google 的 OAuth 2.0 服务器发送请求

如需获取用户授权，请向 Google 的授权服务器 (https://accounts.google.com/o/oauth2/v2/auth) 发送请求。此端点用于处理活跃会话查找、用户身份验证和用户意见征求。该端点只能通过 SSL 访问，并且会拒绝 HTTP（非 SSL）连接。

对于已安装的应用，授权服务器支持以下查询字符串参数：

授权网址示例

下方的标签页显示了不同重定向 URI 选项的授权网址示例。

这两个网址完全相同，只是 redirect_uri 参数的值不同。这些网址还包含必需的 response_type 和 client_id 参数以及可选的 state 参数。为了便于阅读，每个网址都包含换行符和空格。

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

第 3 步：Google 提示用户授予同意书

在此步骤中，用户决定是否向您的应用授予所请求的访问权限。在此阶段，Google 会显示一个同意窗口，其中显示应用的名称，以及请求权限来使用用户授权凭据进行访问的 Google API 服务，还会显示要授予的访问范围摘要。然后，用户可以同意授予对应用所请求的一个或多个范围的访问权限，也可以拒绝该请求。

在此阶段，您的应用无需执行任何操作，只需等待 Google 的 OAuth 2.0 服务器的响应，以确定是否授予了任何访问权限。以下步骤将说明该响应。

第 4 步：处理 OAuth 2.0 服务器响应

应用接收授权响应的方式取决于其使用的重定向 URI scheme。无论采用哪种方案，响应都会包含授权代码 (code) 或错误 (error)。例如，error=access_denied 表示用户拒绝了请求。

如果用户向您的应用授予访问权限，您可以按照下一步中的说明，将授权代码换成访问令牌和刷新令牌。

第 5 步：将授权代码换成刷新令牌和访问令牌

如需使用授权代码交换访问令牌，请调用 https://oauth2.googleapis.com/token 端点并设置以下参数：

以下代码段显示了一个示例请求：

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google 会返回一个包含短期有效的访问令牌和刷新令牌的 JSON 对象，以响应此请求。

响应包含以下字段：

以下代码段显示了示例响应：

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

第 6 步：检查用户授予了哪些范围

当您请求多项权限（范围）时，用户可能不会向您的应用授予对所有这些权限的访问权限。您的应用必须验证实际授予了哪些范围，并妥善处理某些权限被拒绝的情况，通常是通过停用依赖于这些被拒绝范围的功能。

不过，也有例外情况。具有全网域授权的 Google Workspace 企业应用或标记为可信的应用会绕过精细权限同意页面。对于这些应用，用户不会看到精细的权限同意屏幕。相反，您的应用要么会获得所有请求的范围，要么不会获得任何范围。

如需了解更详细的信息，请参阅如何处理精细权限。

如需检查用户是否已向您的应用授予对特定范围的访问权限，请检查访问令牌响应中的 scope 字段。access_token 授予的访问权限范围，以空格分隔的区分大小写的字符串列表表示。

例如，以下示例访问令牌响应表明，用户已向您的应用授予查看、修改和永久删除用户 YouTube 视频、评分、评论和字幕的权限：

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

调用 Google API

应用获得访问令牌后，如果 API 所需的访问范围已获授权，您就可以使用该令牌代表指定的用户账号调用 Google API。为此，请在向 API 发出的请求中添加访问令牌，方法是添加 access_token 查询参数或 Authorization HTTP 标头 Bearer 值。如果可以，最好使用 HTTP 标头，因为查询字符串往往会显示在服务器日志中。在大多数情况下，您可以使用客户端库来设置对 Google API 的调用（例如，调用 YouTube Data API 时）。

请注意，YouTube Data API 仅支持拥有和管理多个 YouTube 频道的 YouTube 内容所有者（例如唱片公司和电影制片厂）的服务账号。

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

HTTP GET 示例

使用 Authorization: Bearer HTTP 标头对 youtube.channels 端点（YouTube Data API）的调用可能如下所示。请注意，您需要指定自己的访问令牌：

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl 示例

您可以使用 curl 命令行应用测试这些命令。下面是一个使用 HTTP 标头选项（首选）的示例：

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

刷新访问令牌

访问令牌会定期过期，并成为相关 API 请求的无效凭据。如果您请求离线访问与令牌关联的范围，则可以刷新访问令牌，而不提示用户授予权限（包括用户不在场时）。

如需刷新访问令牌，您的应用会向 Google 的授权服务器 (https://oauth2.googleapis.com/token) 发送 HTTPS POST 请求，其中包含以下参数：

以下代码段显示了一个示例请求：

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 以及错误代码。

应用重定向方法

保护您的应用

基于时间的访问权限

基于时间的访问权限允许用户在有限的时间内授予您的应用对其数据的访问权限，以完成某项操作。在意见征求流程中，部分 Google 产品会提供基于时间的访问权限，让用户可以选择在有限的时间内授予访问权限。例如， Data Portability API 可实现一次性数据转移。

当用户向您的应用授予基于时间的访问权限时，刷新令牌将在指定时长后过期。请注意，在特定情况下，刷新令牌可能会提前失效；如需了解详情，请参阅这些情况。在授权码交换响应中返回的 refresh_token_expires_in 字段表示在这种情况下刷新令牌的剩余有效时间。

延伸阅读

IETF 当前最佳实践 OAuth 2.0 for Native Apps 确立了本文档中记录的许多最佳实践。