针对移动应用和桌面应用的 OAuth 2.0

本文介绍了安装在手机、平板电脑和 计算机使用 Google 的 OAuth 2.0 端点来授权访问 YouTube Analytics API 或 YouTube Reporting API。

OAuth 2.0 允许用户与应用共享特定数据，同时 用户名、密码和其他隐私信息 例如，应用可以使用 OAuth 2.0 来获取权限 来检索频道的 YouTube 数据分析数据。

已安装的应用会分发到各个设备，并且假定这些应用 不能保守秘密。它们可以在用户使用应用期间或在以下情况下访问 Google API： 应用正在后台运行

此授权流程与 Web 服务器应用。它们的主要区别在于 要求已安装的应用必须打开系统浏览器并提供一个本地重定向 URI 来处理 Google 授权服务器的响应。

替代方案

对于移动应用，您可能希望使用 Google 登录功能： Android 或 iOS。Google 登录功能 客户端库可处理身份验证和用户授权，而且可能更简单 实现比此处所述的较低级别的协议更高

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

库和示例

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

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

前提条件

为您的项目启用 API

任何调用 Google API 的应用都需要在 API Console。

如需为您的项目启用该 API，请按以下步骤操作：

1. Open the API Library 在 Google API Console。
2. If prompted, select a project, or create a new one.
3. 在“库”页面上找到并启用 YouTube Analytics API 和 YouTube Reporting API。许多检索 YouTube 数据分析数据的应用程序也与 YouTube 数据 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 Analytics API 使用以下范围：

YouTube Reporting API 使用以下范围：

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%2Fyt-analytics.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%2Fyt-analytics.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/yt-analytics.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

调用 Google API

在您的应用获得访问令牌后，您就可以使用该令牌调用 Google 代表指定的 用户账号（如果已授予 API 所需的访问权限范围）。为此，请添加 通过添加 access_token 查询来获取对 API 的请求中的访问令牌 参数或 Authorization HTTP 标头 Bearer 值。如有可能， 最好使用 HTTP 标头，因为查询字符串通常显示在服务器日志中。大多数 可以使用客户端库来设置对 Google API 的调用（例如， 调用 YouTube Analytics API）。

请注意，YouTube Analytics API 不支持该服务账号 。YouTube Reporting API 仅支持 拥有并管理多个 YouTube 频道的 YouTube 内容所有者， 唱片公司和电影制片厂

您可以访问以下网址，试用所有 Google API 并查看其作用域： OAuth 2.0 Playground。

HTTP GET 示例

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

GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

curl 示例

您可以使用 curl 命令行应用测试这些命令。这里有 使用 HTTP 标头选项的示例（首选）：

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

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

curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

刷新访问令牌

访问令牌会定期过期，并成为相关 API 请求的无效凭据。您 可以在不提示用户授予权限的情况下刷新访问令牌（包括在用户 不存在）。

为了刷新访问令牌，您的应用会发送 HTTPS POST 向 Google 的授权服务器 (https://oauth2.googleapis.com/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 以及错误代码。

应用重定向方法

保护您的应用

延伸阅读

IETF 现行最佳做法 OAuth 2.0 for 原生应用确立了本文中介绍的许多最佳实践。