此页面由 Cloud Translation API 翻译。

使用 OAuth 2.0 访问 Google API

Google API 使用 OAuth 2.0 协议进行身份验证和授权。Google 支持常见的 OAuth 2.0 用例，如网络服务器、客户端侧、安装程序和有限输入设备应用用例。

首先，从 Google API Console 获取 OAuth 2.0 客户端凭据。然后，您的客户端应用会从 Google 授权服务器请求访问令牌，从响应中提取令牌，然后将此令牌发送到您要访问的 Google API。如需查看将 OAuth 2.0 与 Google 结合使用的交互式演示（包括使用您自己的客户端凭据的选项），请试用 OAuth 2.0 Playground。

本页面概述了 Google 支持的 OAuth 2.0 授权方案，并提供了指向更详细内容的链接。如需详细了解如何使用 OAuth 2.0 进行身份验证，请参阅 OpenID Connect。

基本步骤

所有应用在使用 OAuth 2.0 访问 Google API 时都遵循基本模式。概括来讲，您需要执行以下五个步骤：

1. 从 Google API Console获取 OAuth 2.0 凭据。

访问 Google API Console 以获取 OAuth 2.0 凭据（例如客户端 ID 和客户端密钥），这些凭据对于 Google 和您的应用都是已知的。这组值因您构建的应用类型而异。例如，JavaScript 应用不需要密钥，但 Web 服务器应用需要密钥。

您必须创建适合应用运行平台的 OAuth 客户端，例如：

代码对于服务器端或 JavaScript Web 应用，请使用“web”客户端类型。请勿将此客户端类型用于任何其他应用，例如原生应用或移动应用。
对于 Android 应用，请使用“Android”客户端类型。
对于 iOS 和 macOS 应用，请使用“iOS”客户端类型。
对于通用 Windows 平台应用，请使用“通用 Windows 平台”客户端类型。
电视对于输入受限的设备（例如电视或嵌入式设备），请使用“电视和受限输入设备”客户端类型。
主机对于服务器到服务器的交互，请使用服务账号。

2. 从 Google 授权服务器获取访问令牌。

您的应用必须先获取用于授予 Google API 访问权限的访问令牌，才可以使用该 API 访问非公开数据。一个访问令牌可以授予对多个 API 的不同程度的访问权限。一个名为 scope 的变量形参用于控制访问令牌允许的资源和操作集。在请求访问令牌期间，您的应用会在 scope 参数中发送一个或多个值。

您可以通过多种方式发出此请求，具体取决于您构建的应用类型。例如，JavaScript 应用可能会使用浏览器重定向到 Google 来请求访问令牌，而安装在没有浏览器的设备上的应用则会使用 Web 服务请求。

某些请求需要进行身份验证，用户需要使用自己的 Google 账号登录。登录后，系统会询问用户是否愿意授予您的应用正在请求的一项或多项权限。此过程称为“用户意见征求”。

如果用户授予至少一项权限，Google 授权服务器会向您的应用发送一个访问令牌（或您的应用可用于获取访问令牌的授权代码）以及该令牌授予的访问范围列表。如果用户未授予相应权限，服务器会返回错误。

一般来说，最佳做法是在需要访问权限时逐步请求权限范围，而不是提前请求。例如，如果应用想要支持将活动保存到日历，则不应在用户按下“添加到日历”按钮之前请求 Google 日历访问权限；请参阅增量授权。

3. 检查用户授予的访问权限范围。

将访问令牌响应中包含的范围与访问相关 Google API 所需的范围进行比较，以确定是否可以访问依赖于相关 Google API 的应用功能。停用应用的任何在无法访问相关 API 的情况下无法正常运行的功能。

即使用户授予了所有请求的范围，您请求中包含的范围也可能与响应中包含的范围不一致。请参阅每项 Google API 的文档，了解访问所需的范围。API 可能会将多个范围字符串值映射到单个访问范围，并针对请求中允许的所有值返回相同的范围字符串。示例：当应用请求用户授权 https://www.google.com/m8/feeds/ 范围时，Google People API 可能会返回 https://www.googleapis.com/auth/contacts 范围；Google People API 方法 people.updateContact 需要已授予的 https://www.googleapis.com/auth/contacts 范围。

4. 将访问令牌发送给 API。

应用获取访问令牌后，会通过 HTTP 授权请求标头将令牌发送给 Google API。虽然可以以 URI 查询字符串参数的形式发送令牌，但我们不建议这样做，因为 URI 参数最终可能会出现在不完全安全的日志文件中。此外，根据良好的 REST 实践，应避免创建不必要的 URI 参数名称。

访问令牌仅对令牌请求的 scope 中描述的一组操作和资源有效。例如，如果访问令牌是针对 Google Calendar API 颁发的，则不会授予对 Google Contacts API 的访问权限。不过，您可以将该访问令牌多次发送到 Google 日历 API，以执行类似的操作。

5. 刷新访问令牌（如有必要）。

访问令牌的生命周期是有限的。如果您的应用需要访问 Google API，但访问时间超出单个访问令牌的生命周期，则可以获取刷新令牌。借助刷新令牌，您的应用可以获取新的访问令牌。

场景

Web 服务器应用

Google OAuth 2.0 端点支持使用 PHP、Java、Go、Python、Ruby 和 ASP.NET 等语言和框架的网络服务器应用。

当您的应用将浏览器重定向到 Google 网址时，授权序列即会开始；该网址包含用于指明所请求的访问权限类型的查询参数。 Google 会处理用户身份验证、会话选择和用户意见征求。结果是授权代码，应用可以使用该代码交换访问令牌和刷新令牌。

应用应存储刷新令牌以供日后使用，并使用访问令牌来访问 Google API。访问令牌过期后，应用会使用刷新令牌来获取新的访问令牌。

您的应用向 Google 授权服务器发送令牌请求，接收授权代码，将该代码换成令牌，然后使用该令牌调用 Google API 端点。

如需了解详情，请参阅针对网络服务器应用使用 OAuth 2.0。

已安装的应用

Google OAuth 2.0 端点支持安装在计算机、移动设备和平板电脑等设备上的应用。通过 Google API Console 创建客户端 ID 时，请指定这是一个已安装的应用，然后选择 Android 应用、Chrome 应用、iOS 应用、通用 Windows 平台 (UWP) 应用或桌面应用作为应用类型。

此流程会生成一个客户端 ID（在某些情况下还会生成一个客户端密钥），您需要将该 ID 嵌入到应用的源代码中。（在此上下文中，客户端密钥显然不会被视为 Secret。）

应用应存储刷新令牌以供日后使用，并使用访问令牌来访问 Google API。访问令牌过期后，应用会使用刷新令牌来获取新的访问令牌。

如需了解详情，请参阅针对已安装的应用使用 OAuth 2.0。

客户端 (JavaScript) 应用

Google OAuth 2.0 端点支持在浏览器中运行的 JavaScript 应用。

当您的应用将浏览器重定向到 Google 网址时，授权序列即会开始；该网址包含用于指明所请求的访问权限类型的查询参数。 Google 会处理用户身份验证、会话选择和用户意见征求。

结果是访问令牌，客户端应先验证该令牌，然后再将其包含在 Google API 请求中。当令牌过期时，应用会重复此过程。

您的 JS 应用向 Google 授权服务器发送令牌请求，接收令牌，验证令牌，并使用该令牌调用 Google API 端点。

如需了解详情，请参阅为客户端应用使用 OAuth 2.0。

输入受限的设备上的应用

Google OAuth 2.0 端点支持在输入受限的设备（例如游戏机、摄像机和打印机）上运行的应用。

授权序列从应用向 Google 网址发出 Web 服务请求以获取授权代码开始。响应包含多个参数，包括网址和应用向用户显示的代码。

用户从设备获取网址和代码，然后切换到具有更丰富输入功能的另一部设备或计算机。用户启动浏览器，前往指定网址，登录，然后输入代码。

与此同时，应用会以指定间隔轮询 Google 网址。用户批准访问权限后，Google 服务器的响应会包含访问令牌和刷新令牌。应用应存储刷新令牌以供日后使用，并使用访问令牌来访问 Google API。访问令牌过期后，应用会使用刷新令牌来获取新的访问令牌。

如需了解详情，请参阅为设备使用 OAuth 2.0。

服务账号

Google API（例如 Prediction API 和 Google Cloud Storage）可以代表您的应用执行操作，而无需访问用户的信息。在这些情况下，您的应用需要向 API 证明自己的身份，但无需征得用户同意。同样，在企业场景中，您的应用可以请求对某些资源的委托访问权限。

对于这些类型的服务器间互动，您需要一个服务账号，该账号属于您的应用，而不是某个最终用户。您的应用会代表服务账号调用 Google API，因此无需征得用户同意。（在非服务账号场景中，您的应用会代表最终用户调用 Google API，有时需要用户同意。）

从 Google API Console获取的服务账号凭据包括一个生成的唯一电子邮件地址、一个客户端 ID 和至少一个公钥/私钥对。您可以使用客户端 ID 和一个私钥来创建已签名的 JWT，并以适当的格式构建访问令牌请求。然后，您的应用会将该令牌请求发送到 Google OAuth 2.0 授权服务器，后者会返回一个访问令牌。应用使用该令牌来访问 Google API。当令牌过期时，应用会重复此过程。

您的服务器应用使用 JWT 从 Google 授权服务器请求令牌，然后使用该令牌调用 Google API 端点。不涉及任何最终用户。

如需了解详情，请参阅服务账号文档。

令牌大小

令牌的大小各不相同，但不得超过以下限制：

code 授权代码
256 字节
contextual_token 访问令牌
2048 字节
restore_page 刷新令牌
512 字节

Google Cloud 的 Security Token Service API 返回的访问令牌的结构与 Google API OAuth 2.0 访问令牌类似，但令牌大小限制不同。如需了解详情，请参阅 API 文档。

Google 保留在这些限制范围内更改令牌大小的权利，您的应用必须相应地支持可变的令牌大小。

刷新令牌过期

您必须编写代码来预料已授予的刷新令牌可能不再有效的情况。刷新令牌可能会因以下原因之一而停止工作：

shield_locked 用户已撤消应用的访问权限。
刷新令牌已 6 个月未使用。
用户更改了密码，并且刷新令牌包含 Gmail 范围。
相应用户账号已超出授予的（有效）刷新令牌数量上限。
用户向您的应用授予了基于时间的访问权限，但该权限已过期。
如果管理员将应用范围中请求的任何服务设置为“受限”（错误为 admin_policy_enforced）。
cloud_lock 对于 Google Cloud Platform API - 管理员设置的会话时长可能已超出。

如果 Google Cloud Platform 项目的 OAuth 意见征求屏幕配置为外部用户类型，且发布状态为“测试”，则系统会向该项目发放有效期为 7 天的刷新令牌，除非所请求的 OAuth 范围仅为名称、电子邮件地址和用户个人资料（通过 userinfo.email, userinfo.profile, openid 范围或其 OpenID Connect 等效范围）。

目前，每个 Google 账号的每个 OAuth 2.0 客户端 ID 最多可拥有 100 个刷新令牌。如果您达到此上限，则当您创建新的刷新令牌时，最旧的刷新令牌会自动失效，且系统不会显示警告。此限制不适用于服务账号。

此外，用户账号或服务账号在所有客户端中拥有的刷新令牌总数也存在更高的限制。大多数普通用户不会超出此限制，但用于测试实现的开发者账号可能会超出此限制。

如果您需要授权多个程序、机器或设备，一种解决方法是将每个 Google 账号的授权客户端数量限制为 15 或 20 个。如果您是 Google Workspace 管理员，则可以创建具有管理员权限的其他用户，并使用这些用户来授权部分客户端。

处理 Google Cloud Platform (GCP) 组织的会话控制政策

GCP 组织的管理员可能需要用户在使用 Google Cloud 会话控制功能访问 GCP 资源时频繁重新进行身份验证。此政策会影响对 Google Cloud 控制台、Google Cloud SDK（也称为 gcloud CLI）以及需要 Cloud Platform 范围的任何第三方 OAuth 应用的访问权限。如果用户设置了会话控制政策，那么在会话时长到期后，您的 API 调用将出错，这与刷新令牌被撤消时的情况类似 - 调用将失败，并显示错误类型 invalid_grant；error_subtype 字段可用于区分令牌被撤消和因会话控制政策而导致的失败（例如，"error_subtype": "invalid_rapt"）。由于会话时长可能非常有限（介于 1 小时到 24 小时之间），因此必须通过重新启动身份验证会话来妥善处理此场景。

同样，您不得使用或鼓励使用用户凭据进行服务器到服务器部署。如果用户凭据部署在服务器上以用于长时间运行的作业或操作，并且客户对这些用户应用了会话控制政策，那么当会话时长到期时，服务器应用将无法重新对用户进行身份验证，因此会失败。

如需详细了解如何帮助客户部署此功能，请参阅这篇面向管理员的帮助文章。

客户端库

以下客户端库与热门框架集成，可简化 OAuth 2.0 的实现。日后我们会陆续为这些库添加更多功能。