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 以获取 Google 和您的应用均已知的 OAuth 2.0 凭据,例如客户端 ID 和客户端密钥。这组值取决于您要构建的应用类型。例如,JavaScript 应用不需要 Secret,但 Web 服务器应用需要。
您必须创建与应用将在其上运行的平台对应的 OAuth 客户端,例如:
- 对于服务器端或 JavaScript Web 应用,请使用“Web”客户端类型。请勿将此客户端类型用于任何其他应用,例如原生应用或移动应用。
- 对于 Android 应用,请使用“Android”客户端类型。
- 对于 iOS 和 macOS 应用,请使用“iOS”客户端类型。
- 对于通用 Windows 平台应用,请使用“通用 Windows 平台”客户端类型。
- 对于受限输入设备(例如 TV 或嵌入式设备),请使用“TV 和受限输入设备”客户端类型。
- 如需进行服务器到服务器的交互,请使用服务帐号。
2. 从 Google 授权服务器获取访问令牌。
您的应用必须先获得一个授予访问权限的 API,才能访问您的 API,然后才可以使用 Google API 访问该数据。单个访问令牌可以授予对多个 API 的不同级别的访问权限。名为 scope
的变量参数用于控制访问令牌允许的一组资源和操作。在访问令牌请求期间,您的应用会在 scope
参数中发送一个或多个值。
您可以通过多种方式发出此请求,具体取决于您构建的应用的类型。例如,JavaScript 应用可以使用浏览器重定向到 Google 来请求访问令牌,而安装在未安装浏览器的设备上的应用会使用网络服务请求。
某些请求需要进行身份验证步骤,用户使用自己的 Google 帐号登录。登录后,系统会询问用户是否愿意授予应用请求的一项或多项权限。此过程称为“用户意见征求”。
如果用户至少授予一项权限,Google 授权服务器会向您的应用发送一个访问令牌(或您的应用可用于获取访问令牌的授权代码)以及该令牌授予的访问权限范围列表。如果用户未授予权限,服务器将返回错误。
通常,最好在需要访问权限时逐步请求范围,而不是预先请求。例如,如果应用支持将活动保存到日历,则除非用户按“添加到日历”按钮,否则应用不得请求访问 Google 日历;请参阅增量授权。
3. 检查用户授予的访问权限范围。
根据访问令牌对相关 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 参数最终可能会出现在不完全安全的日志文件中。此外,最好避免创建不必要的 URI 参数名称。
访问令牌仅对令牌请求的 scope
中所述的操作和资源集有效。例如,如果 Google 日历 API 获得了访问令牌,则不会授予对 Google 通讯录 API 的访问权限。不过,您可以针对类似的操作多次将访问令牌发送到 Google Calendar API。
5. 如有必要,请刷新访问令牌。
访问令牌的生命周期是有限的。如果您的应用需要在单个访问令牌的生命周期内访问 Google API,它可以获取刷新令牌。刷新令牌可让您的应用获取新的访问令牌。
场景
Web 服务器应用
Google OAuth 2.0 端点支持使用 PHP、Java、Python、Ruby 和 ASP.NET 等语言和框架的网络服务器应用。
当您的应用将浏览器重定向到 Google 网址时,授权序列即会开始;该网址包含用于指明所请求的访问类型的查询参数。 Google 负责处理用户身份验证、会话选择和用户意见征求事宜。结果是授权代码,应用可以用它来换取访问令牌和刷新令牌。
应用应存储刷新令牌以供将来使用,并使用访问令牌访问 Google API。访问令牌到期后,应用便会使用刷新令牌获取新令牌。

如需了解详情,请参阅为网络服务器应用使用 OAuth 2.0。
已安装的应用
Google OAuth 2.0 端点支持安装在计算机、移动设备和平板电脑上等设备上的应用。通过 Google API Console 创建客户端 ID 时,请指定这是一个已安装的应用,然后选择 Android、Chrome 应用、iOS、Universal Windows Platform (UWP) 或桌面应用作为应用类型。
该过程会生成客户端 ID,在某些情况下还会生成客户端密钥,您可以将其嵌入应用的源代码中。(在这种情况下,客户端密钥显然不会被视为密钥。)
当您的应用将浏览器重定向到 Google 网址时,授权序列即会开始;该网址包含用于指明所请求的访问类型的查询参数。 Google 负责处理用户身份验证、会话选择和用户意见征求事宜。结果是授权代码,应用可以用它来换取访问令牌和刷新令牌。
应用应存储刷新令牌以供将来使用,并使用访问令牌访问 Google API。访问令牌到期后,应用便会使用刷新令牌获取新令牌。

如需了解详情,请参阅 针对已安装的应用使用 OAuth 2.0。
客户端 (JavaScript) 应用
Google OAuth 2.0 端点支持在浏览器中运行的 JavaScript 应用。
当您的应用将浏览器重定向到 Google 网址时,授权序列即会开始;该网址包含用于指明所请求的访问类型的查询参数。 Google 负责处理用户身份验证、会话选择和用户意见征求事宜。
结果会生成一个访问令牌,客户端需要先验证此令牌,然后才能将其包含在 Google API 请求中。当令牌过期时,应用会重复该过程。

如需了解详情,请参阅将 OAuth 2.0 用于客户端应用。
输入受限的设备上的应用
Google OAuth 2.0 端点支持在受限输入设备(如游戏机、摄像机和打印机)上运行。
授权序列始于应用向 Google 网址发出 Web 服务请求以获取授权代码。响应包含几个参数,包括一个网址和一个应用向用户显示的代码。
用户从设备获取网址和代码,然后切换到具有更丰富输入功能的单独设备或计算机。用户启动浏览器,前往指定网址,登录,然后输入代码。
同时,该应用会按指定的时间间隔轮询 Google 网址。用户批准访问之后,Google 服务器的响应会包含访问令牌和刷新令牌。应用应存储刷新令牌以供将来使用,并使用访问令牌访问 Google API。访问令牌到期后,应用便会使用刷新令牌获取新令牌。

如需了解详情,请参阅对设备使用 OAuth 2.0。
服务帐号
Prediction API 和 Google Cloud Storage 等 Google API 可以代表您的应用,而无需访问用户信息。在这些情况下,您的应用需要向 API 证明自己的身份,但不需要用户同意。同样,在企业场景中,您的应用可以请求对某些资源的委托访问权限。
对于这些类型的服务器到服务器交互,您需要一个服务帐号,该帐号属于您的应用而不是某个最终用户。您的应用会代表服务帐号调用 Google API,而无需征得用户同意。(在非服务帐号场景中,您的应用代表最终用户调用 Google API,有时需要征得用户同意。)
您从 Google API Console获取的服务帐号凭据包含生成的唯一电子邮件地址、客户端 ID,以及至少一个公钥/私钥对。您可以使用客户端 ID 和一个私钥来创建已签名的 JWT,并以适当的格式构建访问令牌请求。然后,您的应用会将该令牌请求发送到 Google OAuth 2.0 授权服务器,后者会返回一个访问令牌。应用使用令牌访问 Google API。令牌过期后,应用会重复该过程。

如需了解详情,请参阅 服务帐号文档。
令牌大小
令牌的大小可能会有所不同,不超过以下限制:
- 授权代码:256 字节
- 访问令牌:2048 字节
- 刷新令牌:512 字节
Google Cloud Security Token Service API 返回的访问令牌的结构类似于 Google API OAuth 2.0 访问令牌,但令牌大小限制不同。如需了解详情,请参阅 API 文档。
Google 保留更改这些限制的令牌大小的权利,并且您的应用必须相应地支持可变令牌大小。
刷新令牌过期
您必须编写代码来预测授予的刷新令牌可能失效的可能性。刷新令牌可能会因以下任一原因而停止运行:
- 用户撤消了您的应用的访问权限。
- 刷新令牌已连续六个月未使用。
- 用户更改了密码,刷新令牌包含 Gmail 范围。
- 该用户帐号(已授权)刷新令牌的数量超出了上限。
- 如果管理员
将应用范围中请求的任何服务设置为“受限”(错误为
admin_policy_enforced
)。 - 对于 Google Cloud Platform API,管理员的会话时长可能会超出上限。
如果 Google Cloud Platform 项目的 OAuth 同意屏幕配置为外部用户类型,且发布状态是“测试”,则颁发的刷新令牌将在 7 天后过期,除非请求的唯一 OAuth 范围是名称、电子邮件地址和用户个人资料的子集(通过
userinfo.email, userinfo.profile, openid
范围或其等效的 OpenID Connect)。
目前,每个 OAuth 2.0 客户端 ID 的 Google 帐号最多可以使用 100 个刷新令牌。 如果达到上限,创建新的刷新令牌会自动使最旧的刷新令牌失效,且不会发出警告。此限制不适用于服务帐号。
此外,一个用户帐号或服务帐号在所有客户端上可拥有的刷新令牌总数还有较大的限制。大多数普通用户都不会超过此限制,但用于测试实现效果的开发者帐号可能会。
如果您需要授权多个程序、机器或设备,一种解决方法是将每个 Google 帐号授权的客户端数量限制为 15 或 20 个。如果您是 Google Workspace 管理员,则可以创建拥有管理员权限的其他用户,并使用他们向部分客户端授权。
处理 Google Cloud Platform (GCP) 组织的会话控制政策
GCP 组织的管理员可能需要在用户访问 GCP 资源时经常重新进行身份验证,使用 Google Cloud 会话控制功能。此政策会影响对 Google Cloud 控制台、Google Cloud SDK(也称为 gcloud CLI)的访问以及任何需要 Cloud Platform 范围的第三方 OAuth 应用的访问权限。如果已设置会话控制政策,那么会话时长到期时,您的 API 调用将与刷新令牌被撤消时发生的错误类似 - 调用将失败并显示错误类型 invalid_grant
;error_subtype
字段可用于区分撤消令牌和会话控制政策失败的情况(例如 "error_subtype": "invalid_rapt"
)。由于会话时长在 1 小时内(在 1 小时内)只能受到 2 小时的超长限制。
同样,您不得使用或鼓励使用用户凭据进行服务器到服务器的部署。如果在服务器上为长时间运行的作业或操作部署用户凭据,并且客户对此类用户应用会话控制政策,则服务器应用会失败,因为会话时长到期后将无法重新验证用户身份。
如需详细了解如何帮助客户部署此功能,请参阅这篇有关管理员的帮助文章。
客户端库
以下客户端库与热门框架集成,这使得 OAuth 2.0 的实现变得更简单。我们将逐步为库添加更多功能。