使用OAuth 2.0访问Google API

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

首先,请从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凭据,例如Google和您的应用程序都知道的客户端ID和客户端密钥。值的集合会根据您所构建的应用程序类型而有所不同。例如,JavaScript应用程序不需要密码,而Web服务器应用程序则需要密码。

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

在您的应用程序可以使用Google API访问私有数据之前,它必须获取一个授予该API访问权限的访问令牌。单个访问令牌可以授予对多个API的不同程度的访问。名为scope的变量参数控制访问令牌允许的资源和操作的集合。在访问令牌请求期间,您的应用程序将在scope参数中发送一个或多个值。

发出此请求的方法有几种,并且根据您所构建的应用程序的类型而有所不同。例如,JavaScript应用程序可能会使用浏览器重定向到Google来请求访问令牌,而安装在没有浏览器的设备上的应用程序会使用网络服务请求。

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

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

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

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

将访问令牌响应中包含的范围与根据对相关Google API的访问来访问应用程序功能所需的范围进行比较。禁用您的应用程序的所有功能,这些功能在无法访问相关API的情况下无法运行。

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

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

应用程序获取访问令牌后,会将令牌发送到HTTP授权请求标头中的Google API。可以将令牌作为URI查询字符串参数发送,但是我们不建议这样做,因为URI参数可能最终存储在不完全安全的日志文件中。另外,避免创建不必要的URI参数名称也是REST的良好做法。请注意,查询字符串支持将于2021年6月1日弃用。

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

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

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

情境

Web服务器应用程序

Google OAuth 2.0终结点支持使用诸如PHP,Java,Python,Ruby和ASP.NET之类的语言和框架的Web服务器应用程序。

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

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

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

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

已安装的应用程序

Google OAuth 2.0终结点支持在计算机,移动设备和平板电脑等设备上安装的应用程序。通过Google API Console创建客户端ID时,请指定这是已安装的应用程序,然后选择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

服务帐号

诸如Prediction API和Google Cloud Storage之类的Google API可以代表您的应用程序运行,而无需访问用户信息。在这些情况下,您的应用程序需要向API证明自己的身份,但无需用户同意。同样,在企业方案中,您的应用程序可以请求委派对某些资源的访问。

对于这些类型的服务器到服务器交互,您需要一个服务帐户,该帐户属于您的应用程序而不是单个最终用户。您的应用程序代表服务帐户调用Google API,并且无需用户同意。 (在非服务帐户的情况下,您的应用程序代表最终用户调用Google API,并且有时需要用户同意。)

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

您的服务器应用程序使用JWT从Google授权服务器请求令牌,然后使用令牌调用Google API端点。没有最终用户参与。

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

代币大小

令牌的大小可能有所不同,但上限如下:

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

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

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

刷新令牌到期

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

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

具有为外部用户类型配置的OAuth同意屏幕且发布状态为“测试”的Google Cloud Platform项目的刷新令牌将在7天后过期。

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

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

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

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

GCP组织的管理员可能需要使用Google Cloud会话控制功能在用户访问GCP资源时进行频繁的重新认证此政策会影响对Google Cloud Console,google cloud SDK(也称为gcloud CLI)和需要Cloud Platform作用域的任何第三方OAuth应用程序的访问。如果用户具有会话控制策略,则在会话持续时间到期时,您的API调用将出错,类似于撤销刷新令牌时将发生的错误。由于会话持续时间可能非常有限(介于1小时至24小时之间),因此必须通过重新启动身份验证会话来妥善处理此情况。

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

有关如何帮助您的客户部署此功能的更多信息,请参阅此以管理员为中心的帮助文章。

客户端库

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