本文档介绍了 Web 服务器应用如何使用 Google API 客户端库或 Google OAuth 2.0 端点来进行 OAuth 2.0 授权，从而实现对 YouTube Data API 的访问。

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

此 OAuth 2.0 流程专门用于用户授权。它专为可以存储机密信息并保持状态的应用而设计。经过适当授权的 Web 服务器应用可以在用户与应用互动期间或在用户离开应用后访问 API。

onBehalfOfContentOwner

客户端库

本页面上特定于某语言的示例使用的是 Google API 客户端库来实现 OAuth 2.0 授权。要想运行代码示例，您必须先安装适用于您的语言的客户端库。

当您使用 Google API 客户端库来处理应用的 OAuth 2.0 流程时，客户端库会执行许多应用原本需要自行处理的操作。例如，它会确定应用何时可以使用或刷新存储的访问令牌，以及应用何时必须重新征得用户同意。客户端库还会生成正确的重定向网址，并帮助实现将授权代码换成访问令牌的重定向处理程序。

Google API 客户端库（适用于服务器端应用）支持以下语言：

前提条件

为您的项目启用 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。

http://localhost:8080http://localhost:8080

创建凭据后，从 API Console下载 client_secret.json 文件。将文件安全地存储在只有您的应用可以访问的位置。

确定访问权限范围

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

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

我们还建议您的应用通过增量授权流程请求授权范围的访问权限，在此流程中，您的应用会在用户执行相关操作时请求访问用户数据。此最佳实践有助于用户更轻松地了解您的应用为何需要其请求的访问权限。

YouTube Data API v3 使用以下范围：

https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.channel-memberships.creatorhttps://www.googleapis.com/auth/youtube.force-sslhttps://www.googleapis.com/auth/youtube.readonlyhttps://www.googleapis.com/auth/youtube.uploadhttps://www.googleapis.com/auth/youtubepartnerhttps://www.googleapis.com/auth/youtubepartner-channel-audit

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

语言专属要求

如需运行本文档中的任何代码示例，您需要拥有 Google 账号、互联网访问权限和网络浏览器。如果您使用的是某个 API 客户端库，另请参阅下文中的特定于语言的要求。

获取 OAuth 2.0 访问令牌

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

下表简要总结了这些步骤：

  1. 您的应用会确定所需的权限。
  2. 您的应用会将用户重定向到 Google，同时提供所请求的权限列表。
  3. 用户决定是否向您的应用授予相应权限。
  4. 您的应用会了解用户的决定。
  5. 如果用户授予了所请求的权限，您的应用会检索代表用户发出 API 请求所需的令牌。

第 1 步：设置授权参数

第一步是创建授权请求。该请求会设置用于标识您的应用并定义用户将被要求向您的应用授予的权限的参数。

  • 如果您使用 Google 客户端库进行 OAuth 2.0 身份验证和授权，则需要创建并配置一个定义这些参数的对象。
  • 如果您直接调用 Google OAuth 2.0 端点，则会生成一个网址，并在该网址上设置参数。

以下标签页介绍了 Web 服务器应用支持的授权参数。 特定于语言的示例还展示了如何使用客户端库或授权库来配置设置这些参数的对象。

Google 授权服务器支持以下适用于 Web 服务器应用的查询字符串参数：

client_idredirect_uriclient_idredirect_uri_mismatchhttphttps/response_typecodescopehttps://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.channel-memberships.creatorhttps://www.googleapis.com/auth/youtube.force-sslhttps://www.googleapis.com/auth/youtube.readonlyhttps://www.googleapis.com/auth/youtube.uploadhttps://www.googleapis.com/auth/youtubepartnerhttps://www.googleapis.com/auth/youtubepartner-channel-auditaccess_typeonlineofflineofflinestateredirect_uri?name=valueredirect_uristatestateinclude_granted_scopestrueenable_granular_consenttruefalselogin_hintsubpromptnoneconsentselect_account

第 2 步：重定向到 Google 的 OAuth 2.0 服务器

将用户重定向到 Google 的 OAuth 2.0 服务器，以启动身份验证和授权流程。通常，这种情况会在您的应用首次需要访问用户数据时发生。对于增量授权，当应用首次需要访问尚未获得访问权限的其他资源时，也会执行此步骤。

Google 的 OAuth 2.0 服务器会验证用户身份，并征得用户同意您的应用访问所请求的范围。系统会使用您指定的重定向网址将响应发回到您的应用。

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

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

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

admin_policy_enforceddisallowed_useragentWKWebViewSFSafariViewControllerorg_internalinvalid_clientdeleted_clientinvalid_grantredirect_uri_mismatchredirect_uriredirect_uriinvalid_request

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

OAuth 2.0 服务器会使用请求中指定的网址来响应应用的访问请求。

如果用户批准了访问请求，响应中就会包含授权代码。如果用户未批准请求，响应中会包含错误消息。返回到网络服务器的授权代码或错误消息会显示在查询字符串中，如下所示：

错误响应：

https://oauth2.example.com/auth?error=access_denied

授权代码响应：

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

OAuth 2.0 服务器响应示例

您可以点击以下示例网址来测试此流程，该网址会请求只读权限以查看您 Google 云端硬盘中文件的元数据，并请求只读权限以查看您的 Google 日历活动： 

http://localhost/oauth2callback404 NOT FOUND

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

Web 服务器收到授权代码后，可以用该授权代码来换取访问令牌。

invalid_grant

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

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

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

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

调用 Google API

完整示例

以下示例在用户完成身份验证并授权应用管理其 YouTube 账号后，会输出一个 JSON 格式的对象，其中包含有关该用户 YouTube 频道的信息。

重定向 URI 验证规则

Google 会对重定向 URI 应用以下验证规则，以帮助开发者确保应用安全无虞。您的重定向 URI 必须遵循以下规则。如需了解下文中提及的网域、主机、路径、查询、方案和 userinfo 的定义，请参阅 RFC 3986 第 3 节。 

“googleusercontent.com”goo.gl“/google-callback/”“/google-callback”“/..”“\..”'*'%00%C0%80

增量授权

在 OAuth 2.0 协议中，您的应用会请求授权以访问资源，这些资源由范围标识。在需要资源时请求授权被认为是最佳用户体验实践。为了实现这种做法，Google 的授权服务器支持增量授权。借助此功能，您可以根据需要请求范围，并且如果用户授予新范围的权限，则会返回一个授权代码，该代码可用于换取包含用户已授予项目的所有范围的令牌。

例如，假设某应用可帮助用户查找有趣的本地活动。用户可以通过该应用观看有关活动的视频、为视频评分，以及将视频添加到播放列表中。用户还可以使用该应用将活动添加到自己的 Google 日历中。

https://www.googleapis.com/auth/youtube.force-sslhttps://www.googleapis.com/auth/calendar

如需实现增量授权，您需要完成请求访问令牌的正常流程，但要确保授权请求包含之前授予的范围。此方法可让您的应用避免管理多个访问令牌。

以下规则适用于通过增量授权获得的访问令牌：

scope

第 1 步：设置授权参数中的特定于语言的代码示例以及第 2 步：重定向到 Google 的 OAuth 2.0 服务器中的示例 HTTP/REST 重定向网址均使用增量授权。下面的代码示例还展示了使用增量授权时需要添加的代码。

Refreshing an access token (offline access)

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

online

Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.

令牌撤消

应用还可以通过程序化方式撤消授予自身的访问权限。 在以下情况下，以程序化方式撤消授权非常重要：用户取消订阅、移除应用，或者应用所需的 API 资源发生了重大变化。换句话说，移除过程的一部分可能包括 API 请求，以确保移除之前授予应用的权限。

基于时间的访问权限

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

refresh_token_expires_in
https://schemas.openid.net/secevent/risc/event-type/sessions-revokedhttps://schemas.openid.net/secevent/oauth/event-type/token-revokedhttps://schemas.openid.net/secevent/risc/event-type/account-disabled