使用 OAuth 2.0 访问 Google API

谷歌的API使用的OAuth 2.0协议进行身份验证和授权。 Google 支持常见的 OAuth 2.0 方案,例如用于 Web 服务器、客户端、已安装和有限输入设备应用程序的方案。

首先,获得来自OAuth 2.0用户凭据 Google API Console 。然后,您的客户端应用程序从 Google 授权服务器请求访问令牌,从响应中提取令牌,并将令牌发送到您要访问的 Google API。对于使用OAuth 2.0与谷歌的互动演示(包括利用自己的客户端证书的选项),实验用的OAuth 2.0游乐场

此页面概述了 Google 支持的 OAuth 2.0 授权方案,并提供了指向更详细内容的链接。有关使用OAuth 2.0认证的详细信息,请参阅ID连接

基本步骤

在使用 OAuth 2.0 访问 Google API 时,所有应用程序都遵循基本模式。在较高级别上,您可以执行以下五个步骤:

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

访问 Google API Console获得OAuth 2.0凭据,如已知为谷歌和你的应用程序客户端ID和客户端密钥。这组值因您正在构建的应用程序类型而异。例如,JavaScript 应用程序不需要密码,但 Web 服务器应用程序需要。

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

在您的应用程序可以使用 Google API 访问私有数据之前,它必须获得授予对该 API 访问权限的访问令牌。单个访问令牌可以授予对多个 API 不同程度的访问权限。一种可变参数调用scope控制所述一组资源和操作的,一个访问令牌许可证。在访问令牌请求,你的应用程序中发送一个或多个值scope参数。

有多种方法可以发出此请求,它们因您正在构建的应用程序类型而异。例如,JavaScript 应用程序可能使用浏览器重定向到 Google 来请求访问令牌,而安装在没有浏览器的设备上的应用程序使用 Web 服务请求。

某些请求需要用户使用其 Google 帐户登录的身份验证步骤。登录后,系统会询问用户是否愿意授予您的应用程序请求的一项或多项权限。这个过程被称为用户的同意

如果用户授予至少一项权限,Google 授权服务器会向您的应用程序发送一个访问令牌(或您的应用程序可用于获取访问令牌的授权代码)以及该令牌授予的访问范围列表。如果用户没有授予权限,服务器将返回错误。

通常最佳做法是在需要访问时增量请求范围,而不是预先请求。例如,想要支持将事件保存到日历的应用程序在用户按下“添加到日历”按钮之前不应请求访问 Google 日历;看到增量授权

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

将访问令牌响应中包含的范围与访问依赖于相关 Google API 的应用程序的特性和功能所需的范围进行比较。禁用无法访问相关 API 的应用程序的任何功能。

您的请求中包含的范围可能与您的响应中包含的范围不匹配,即使用户授予了所有请求的范围。有关访问所需的范围,请参阅每个 Google API 的文档。 API 可以将多个范围字符串值映射到单个访问范围,为请求中允许的所有值返回相同的范围字符串。例:谷歌API的人可能返回的范围https://www.googleapis.com/auth/contacts当一个应用程序要求用户授权的范围https://www.google.com/m8/feeds/ ;谷歌的API人们方法people.updateContact需要的授予范围https://www.googleapis.com/auth/contacts

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

后的应用程序获得的访问令牌时,它发送该令牌在谷歌的API HTTP授权请求头。可以将令牌作为 URI 查询字符串参数发送,但我们不建议这样做,因为 URI 参数最终会出现在不完全安全的日志文件中。此外,避免创建不必要的 URI 参数名称也是一种很好的 REST 实践。

访问令牌的有效期只为集所描述的操作和资源的scope令牌请求。例如,如果为 Google Calendar API 颁发了访问令牌,则它不会授予对 Google Contacts API 的访问权限。但是,您可以将该访问令牌多次发送到 Google 日历 API 以进行类似操作。

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

访问令牌的生命周期有限。如果您的应用程序需要在单个访问令牌的生命周期之外访问 Google API,它可以获得刷新令牌。刷新令牌允许您的应用程序获取新的访问令牌。

场景

网络服务器应用程序

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

当您的应用程序将浏览器重定向到 Google URL 时,授权序列就开始了; URL 包含指示所请求访问类型的查询参数。 Google 处理用户身份验证、会话选择和用户同意。结果是一个授权代码,应用程序可以用它来交换访问令牌和刷新令牌。

应用程序应存储刷新令牌以备将来使用,并使用访问令牌访问 Google API。一旦访问令牌过期,应用程序将使用刷新令牌来获取新令牌。

您的应用程序向 Google 授权服务器发送令牌请求,接收授权代码,交换令牌代码,并使用令牌调用 Google API 端点。

有关详细信息,请参阅使用OAuth 2.0 Web服务器应用程序

已安装的应用程序

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

该过程会生成一个客户端 ID,在某些情况下还会生成一个客户端机密,您将其嵌入到应用程序的源代码中。 (在这种情况下,客户端机密显然不被视为机密。)

当您的应用程序将浏览器重定向到 Google URL 时,授权序列就开始了; URL 包含指示所请求访问类型的查询参数。 Google 处理用户身份验证、会话选择和用户同意。结果是一个授权代码,应用程序可以用它来交换访问令牌和刷新令牌。

应用程序应存储刷新令牌以备将来使用,并使用访问令牌访问 Google API。一旦访问令牌过期,应用程序将使用刷新令牌来获取新令牌。

您的应用程序向 Google 授权服务器发送令牌请求,接收授权代码,交换令牌代码,并使用令牌调用 Google API 端点。

有关详细信息,请参阅使用OAuth 2.0安装的应用程序

客户端 (JavaScript) 应用程序

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

当您的应用程序将浏览器重定向到 Google URL 时,授权序列就开始了; URL 包含指示所请求访问类型的查询参数。 Google 处理用户身份验证、会话选择和用户同意。

结果是访问令牌,客户端应在将其包含在 Google API 请求中之前对其进行验证。当令牌过期时,应用程序重复该过程。

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

有关详细信息,请参阅使用OAuth 2.0客户端应用程序

在有限输入设备上的应用

Google OAuth 2.0 端点支持在有限输入设备(例如游戏机、摄像机和打印机)上运行的应用程序。

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

用户从设备获取 URL 和代码,然后切换到具有更丰富输入功能的单独设备或计算机。用户启动浏览器,导航到指定的 URL,登录并输入代码。

同时,应用程序以指定的时间间隔轮询 Google URL。用户批准访问后,来自 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 端点。不涉及最终用户。

有关详细信息,请参阅服务帐户的文档

代币大小

令牌的大小可能会有所不同,最大为以下限制:

  • 授权码:256字节
  • 访问令牌:2048 字节
  • 刷新令牌:512 字节

访问由谷歌Cloud的返回的标记安全令牌服务API的结构类似于谷歌API的OAuth 2.0访问令牌,但有不同的令牌大小限制。有关详细信息,请参阅API文档

Google 保留在这些限制内更改令牌大小的权利,并且您的应用程序必须相应地支持可变的令牌大小。

刷新令牌过期

您必须编写代码以预测授予的刷新令牌可能不再起作用的可能性。由于以下原因之一,刷新令牌可能会停止工作:

  • 用户已经撤销你的应用程序的访问
  • 刷新令牌已六个月未使用。
  • 用户更改了密码,刷新令牌包含 Gmail 范围。
  • 用户帐户已超过授予的(实时)刷新令牌的最大数量。
  • 用户属于具有有效会话控制策略的 Google Cloud Platform 组织。

为外部用户类型配置了 OAuth 同意屏幕且发布状态为“测试”的 Google Cloud Platform 项目会收到一个刷新令牌,该令牌将在 7 天后到期。

目前,每个 OAuth 2.0 客户端 ID 每个 Google 帐户的刷新令牌限制为 50 个。如果达到限制,则创建新的刷新令牌会自动使最旧的刷新令牌无效,而不会发出警告。此限制并不适用于服务帐户

用户帐户或服务帐户在所有客户端上可以拥有的刷新令牌总数也有更大的限制。大多数普通用户不会超过此限制,但用于测试实现的开发人员帐户可能会超过此限制。

如果您需要授权多个程序,机器或设备,一个解决办法是限制你每个谷歌账户授权给15或20。如果你是一个客户端的数量谷歌工作区管理员,您可以创建具有管理权限,其他用户使用它们来授权一些客户端。

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

而他们访问GCP资源GCP组织的管理员可能需要用户频繁重认证,使用谷歌云会话控制功能。此政策影响访问谷歌云端控制台中,谷歌云SDK (又称gcloud CLI),这需要云平台范围内的任何第三方OAuth应用。如果用户拥有代替会话控制政策,然后在会话持续时间届满后,你的API调用时会报错了类似令牌是否被撤销的刷新会发生什么-电话将错误类型失败invalid_token ;子错误类型可用于区分撤销令牌和由于会话控制策略导致的失败。由于会话持续时间可能非常有限(在 1 小时到 24 小时之间),因此必须通过重新启动身份验证会话来妥善处理这种情况。

同样,您不得使用或鼓励使用用户凭据进行服务器到服务器部署。如果用户凭据部署在服务器上用于长时间运行的作业或操作,并且客户对此类用户应用会话控制策略,则服务器应用程序将失败,因为在会话持续时间到期时将无法重新验证用户。

有关如何帮助客户部署此功能的更多信息,请参见本管理为重点的帮助文章。

客户端库

以下客户端库与流行的框架集成,这使得实现 OAuth 2.0 更简单。随着时间的推移,更多功能将添加到库中。