Eric Bidelman，Google 数据 API 团队
2008 年 9 月
简介
对开发者来说，这是一个激动人心的时刻。我们已经开始看到网络上广泛采用多种开放标准，如您所知，Google 一直是标准的拥护者，并且正在培养开源社区。
最近，所有 Google 数据 API 都采用了 OAuth 支持。OAuth 是一种开放式协议，旨在标准化桌面和 Web 应用访问用户的私有数据的方式。OAuth 提供了一种以标准安全方式执行 API 身份验证的方法。作为程序员，我们会指示用户尽可能重复使用代码。OAuth 有助于开发者减少他们编写的重复代码量，并更轻松地创建与来自不同不同提供商的多项服务搭配使用的工具。
观众
本文假定您熟悉一个或多个 Google Data API，但并不一定熟悉 OAuth 背后的概念。 如果您刚开始使用 OAuth，或者只是想了解 OAuth，不妨看看。本文将为您简要介绍一些概念。我还将讨论 Google OAuth 实现的详情。
本文档还面向熟悉 AuthSub 使用方法的开发者，尤其是在使用增强型安全模式注册的用户。在学习过程中，我会尽量突出这两种协议之间的相似之处和不同之处。如果您有使用 AuthSub 的应用，则可以参考这些信息来迁移到 OAuth。OAuth 是一种更开放的现代协议。
术语
了解 OAuth 就是了解其术语。OAuth 规范和 Google 的适用于 Web 应用的 OAuth 身份验证文档主要依赖于某些定义，所以让我们逐一说明每种定义的 Google OAuth 实现方式意味着什么。
- “OAuth 舞蹈”
我的非官方术语，用于描述完整的 OAuth 身份验证/授权流程。
- (OAuth) 请求令牌
初始令牌可以让 Google 知道您的应用正在请求访问某个 Google 数据 API。OAuth 舞蹈的第二步是让用户手动授予对其数据的访问权限。如果此步骤成功，则请求令牌会获得授权。
- (OAuth) 访问令牌
舞蹈的最后一步是用已获授权的请求令牌换取访问令牌。您的应用获得此令牌后，除非该令牌被撤消，否则用户无需再次执行 OAuth 舞蹈测试。
与 AuthSub 相似：
OAuth 访问令牌与安全的 AuthSub 会话令牌是相同的。 - (OAuth) 端点
这些是对应用进行身份验证并获取访问令牌所需的 URI。总共有三个 - OAuth 流程的每个步骤各有一个。 Google 的 OAuth 端点：
获取请求令牌： https://www.google.com/accounts/OAuthGetRequestToken为请求令牌授权： https://www.google.com/accounts/OAuthAuthorizeToken升级到访问令牌： https://www.google.com/accounts/OAuthGetAccessToken与 AuthSub 相似：
将已授权的请求令牌换成访问令牌类似于在https://www.google.com/accounts/AuthSubRequestToken和https://www.google.com/accounts/AuthSubSessionToken分别将单次使用的 AuthSub 令牌升级为长期会话令牌。 不同之处在于 AuthSub 没有初始请求令牌的概念。而是从AuthSubRequestToken授权页面启动令牌流程。 - (OAuth) 服务提供商
就 Google 数据 API 而言，此提供程序为 Google。通常，服务提供商用于描述提供 OAuth 端点的网站或网络服务。 OAuth 服务提供商的另一个例子是 MySpace。
- (OAuth) 使用方
请求访问用户的数据（即您的应用）的程序。OAuth 协议非常灵活，因为它支持各种不同类型的客户端（网页、已安装、桌面设备、移动设备）。
注意：尽管 OAuth 协议支持桌面/已安装应用用例，但 Google 仅支持适用于 Web 应用的 OAuth。
开始使用
注册
您需要进行少量设置，才能开始将 OAuth 用于 Google Data API。由于所有 OAuth 请求都必须进行数字签名，因此您需要先注册域名并向 Google 上传公共证书。如需详细了解如何执行此操作，请参阅注册基于网络的应用和生成用于注册模式的密钥和证书。
对请求进行签名
注册域名后，您就可以开始对请求进行签名了。OAuth 最难的概念之一是如何正确构建 oauth_signature 和签名基字符串的概念。基本字符串是您使用私钥签名的数据（使用 RSA_SHA1）。结果是您为 oauth_signature 设置的值。
请求示例
GET - http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 中用户的 Google 日历列表
| 基本字符串格式 | base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters |
|---|---|
| 基本字符串示例 | GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime |
| HTTP 请求示例 |
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0" |
注意：这仅用作表示法。您的 oauth_signature 将长得多。
关于基本字符串的注意事项：
orderby=starttime查询参数与其余oauth_*参数一起按字典顺序的字节值排序。- 此字符串也不包含“?”字符。
base-http-request-url部分仅包含采用网址编码的基准网址：http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull。oauth_token是双重网址编码。
关于 Authorization 标头的注意事项：
Authorization标头中oauth_*参数的顺序无关紧要。- 标头不包含
orderby=starttime，与基本字符串相同。该查询参数将作为请求网址的一部分进行维护。
如需详细了解如何使用 OAuth 对请求进行签名，请参阅为 OAuth 请求签名。
与 AuthSub 的区别：
下面提供了一个使用安全 AuthSub 的示例对比：
| 基本字符串格式 | base_string = http-method http-request-URL timestamp nonce |
|---|---|
| 基本字符串示例 |
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d |
| HTTP 请求示例 |
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1" |
如需详细了解如何使用 AuthSub 对请求进行签名，请参阅对 AuthSub 请求进行签名。
OAuth 园地工具
目的
部分用户建议 OAuth 采用较长的学习曲线。与 Google 的其他身份验证 API 相比，我同意您的看法。当您扩展应用以使用其他（非 Google）服务时，OAuth 的优势将非常明显。编写一段用于不同服务提供商及其 API 的身份验证代码，听起来不错。 稍后，您将感谢自己学习该协议。
OAuth 园地是我开发的一款工具，旨在帮助开发者解决其 OAuth 问题。 您可以使用 Playground 调试问题、检查您自己的实现方案，或试用 Google Data API。
它有什么作用？
- 说明 OAuth 身份验证流程：获取请求令牌、授权令牌并将其升级为访问令牌。
- 为每个请求显示正确的签名基本字符串。
- 为每个请求显示正确的
Authorization标头。 - 演示如何使用
oauth_token与经过身份验证的 Google 数据 Feed 互动。 您可以GET/POST/PUT/DELETE获取数据。 - 直接在浏览器中查看经过身份验证的 Feed。
- 让您可以测试自己的
oauth_consumer_key（注册网域）和私钥。 - 了解您的
oauth_token可以使用哪些 Google 数据 Feed 服务。
演示运行
第 1 步：选择范围首先，请选择一个或多个范围，以确定您要使用的 API。在本演示中，我将申请一个适用于 Blogger 和 Google 通讯录的令牌。 与 AuthSub 相似： |
|
第 2 步：修改 OAuth 参数和设置目前，请勿修改“修改 OAuth 参数”框中的任何设置。稍后，您可以使用自己的私钥进行测试，只需将 注意： 除了 与 AuthSub 的区别： |
 |
第 3-5 步：获取访问令牌获取 OAuth 访问令牌需要执行三个步骤。第一步是检索请求令牌。这会告知 Google 您的应用正在启动 OAuth 舞蹈流程。 首先，点击“获取令牌”框中的“申请令牌”按钮。 某些字段会填充数据。
|
|
|
接下来，点击“获取令牌”框中的“授权”按钮。 在此授权页面上，点击“授予访问权限”按钮，为请求令牌授权并重定向回 OAuth 园地。 与 AuthSub 的相似之处： 与 AuthSub 的区别： 提示：如果您要编写 Web 应用，最好指定 |
|
|
最后，点击“获取令牌”框中的“访问令牌”按钮。 此操作会升级已获授权的请求令牌（如红色的“访问令牌”）标签。 如果您要提取新令牌，请点击“重新开始”以重新启动 OAuth 舞蹈流程。 现在我们可以做一些有趣的事情了！ |
|
使用访问令牌
现在，您可以查询 Feed、插入、更新或删除数据了。在处理实际数据时，请谨慎执行最后三种 HTTP 方法！
提示：如需探索适用于您的访问令牌的 Feed，请点击“可用的 Feed”按钮。
下面是一个查询示例：GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3
此示例在特定博客上返回的博文不超过三篇。您还可以通过点击语法突出显示区域下方的“在浏览器中查看”链接，直接在浏览器中查看返回的 Feed/条目。
示例：如何更新帖子
- 在要更新的帖子中找到带有 rel="edit" 的
<link>元素。该结果应如下所示：<link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>
将 href 网址粘贴到“输入 Google 数据 Feed”输入框中。
- 点击语法突出显示面板顶部的“查看纯文本”，复制现有条目的 XML。请仅复制响应正文，而不复制标头。
- 将 HTTP 方法下拉菜单更改为
PUT。 - 点击该下拉菜单下方的“输入博文数据”，然后将
<entry>XML 粘贴到弹出式窗口中。 - 点击“执行”按钮。
服务器将会返回 200 OK。
提示：请不要手动复制 edit 链接，而是取消选中“语法突出显示？”复选框。完成查询后，您可以点击 XML 响应正文中的链接。
总结
AtomPub/Atom Publishing Protocol（Google Data API 的底层协议）和 OAuth 等技术可帮助推动网络向前发展。 随着越来越多的网站开始采用这些标准，开发者将会获胜。创建杀手级应用突然会变得没那么困难。
如果您对 OAuth 园地有任何疑问或评论，或者正在将 OAuth 用于 Google API，请在 G Suite API 和 Marketplace API 支持论坛中与我们联系。