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

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

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

安装式应用会分发给各个设备，系统会假定这些应用无法保密。当用户位于应用中或应用在后台运行时，他们可以访问 Google API。

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

替代方案

对于移动应用，您可能更倾向于使用适用于 Android 或 iOS 的 Google 登录功能。Google 登录客户端库可以处理身份验证和用户授权，而且这些库的实现可能比此处介绍的较低级别的协议更简单。

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

库和示例

我们建议您使用以下库和示例来帮助您实现本文档中所述的 OAuth 2.0 流程：

• AppAuth for Android 库
• AppAuth for iOS 库
• 适用于应用的 OAuth：Windows 示例

前提条件

为您的项目启用 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. 依次点击创建凭据 > OAuth 客户端 ID。
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 架构。无论使用哪一种方案，响应都会包含授权代码 (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"
}

调用 Google API

在您的应用获得访问令牌后，如果已授予 Google API 所需的访问权限范围，您就可以使用该令牌代表指定用户帐号调用该 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

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

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

延伸阅读

IETF 当前最佳实践适用于原生应用的 OAuth 2.0 确立了本文所述的许多最佳实践。