Google 数据协议中的身份验证和授权

警告：本页面介绍的是 Google 的旧版 API，即 Google 数据 API；它仅与 Google 数据 API 目录中列出的许多 API 相关，其中许多 API 已替换为较新的 API。如需了解特定新 API，请参阅新 API 的文档。如需了解如何使用较新的 API 向请求授权，请参阅 Google 帐号身份验证和授权。

对于某些类型的活动，第三方应用通常需要对用户的 Google 帐号的有限访问权限。为确保用户数据不会遭到滥用，所有访问权限请求都必须经过帐号持有人批准。访问权限控制包含两个部分，即身份验证和授权。

身份验证服务允许用户使用 Google 帐号登录您的应用。

授权服务可让用户向您的应用提供他们存储在 Google 应用中的数据的访问权限。Google 非常重视隐私，任何需要访问用户数据的应用都必须获得用户授权。

身份验证和授权服务统称为“身份验证”。

对 Google API 的身份验证和授权可让第三方应用对某些类型的 Activity 限制访问用户的 Google 帐号。本文档介绍了可用的身份验证机制，并说明了每种机制为您的应用提供的机制。

  • Google 登录可让用户使用其 Google 凭据轻松登录您的网站。它包含一组可轻松集成到不同设备上的工具。
  • OAuth 2.0 是所有 Google API 的授权协议。OAuth 2.0 依靠 SSL 确保安全性，而不是要求您的应用直接进行加密签名。此协议可让您的应用请求访问与用户的 Google 帐号关联的数据。
  • 使用 OAuth 2.0 登录 (OpenID Connect) 让用户通过其 Google 帐号登录进行身份验证。这取代了 OpenID，OpenID 的用户应计划迁移到使用 OAuth 2.0 登录。

如果您的应用是小工具（用于 iGoogle 或其他 OpenSocial 容器），请参阅小工具身份验证部分。

注意：本文档旨在简要介绍每种身份验证方法。如需详细了解每种方法，请参阅完整的 Google 帐号身份验证 API 文档。

另请参阅 Google Accounts API 群组，了解如何使用 Google 帐号 API。

OAuth - 适用于网站和应用的授权

许多 Google 服务都允许第三方访问用户生成的数据，例如日历或文档数据，前提是用户已授权访问这些数据。此功能可让用户出于各种目的在 Google 应用和第三方应用之间共享和交换数据。

Google 支持获取 OAuth 1.0 和 OAuth 2.0 这两种授权访问用户的 Google 数据的版本，它们都提供访问 Web 应用和已安装的应用的权限。

适用于 Web 应用和已安装应用的 OAuth 2.0

Web 应用或已安装的应用可以使用经过简化的新 OAuth 2.0 协议来授权访问与 Google 帐号相关联的数据。如需详细了解如何通过 Google 实现 OAuth 2.0，请参阅关于 OAuth 2.0 的文档。

适用于 Web 应用的 OAuth 1.0

如果需要授权访问与 Google 帐号或 Google Apps 帐号相关联的数据的 Web 应用，可以使用 Google 的 OAuth API 实现。有关为 Web 应用实现 OAuth 的完整信息（包括示例），请参阅 OAuth for Web Apps 指南或查看本文档中的概览。

适用于已安装应用的 OAuth 1.0

用户计算机和移动设备上安装的应用可以使用 OAuth 授权访问与 Google 帐号相关联的数据。有关针对安装式应用实现 OAuth 的完整信息，请参阅安装式应用的 OAuth 指南，或参阅本文档中的概览。

将 OAuth 用于 Web 应用

所有 Google Data API 均支持 OAuth，OAuth 是一种用于授权在 Web 应用中使用数据的开放标准。所有发出 OAuth 请求的 Web 应用都必须上传安全证书，并向 Google 注册。如需了解详情，请参阅注册基于网络的应用。

Google 数据 API 客户端库提供了一些方法，可帮助您在 Web 应用中使用 OAuth。具体而言，您可以通过多种方法来构建请求令牌、为请求令牌授权以及用已获授权的请求令牌换取访问令牌。在向 Google 数据服务发出请求时，这些库还会处理必要的签名算法。有关如何将 OAuth 与 Google Data API 客户端库结合使用的详尽示例，请参阅将 OAuth 与 Google Data API 客户端库搭配使用。

OAuth 授权流程

OAuth 授权流程涉及您的 Web 应用、Google 授权服务器和最终用户之间的一系列互动。

基本流程如下：

  1. 您的应用会请求访问权限，并从 Google 的授权服务器获取未经授权的请求令牌。
  2. Google 会要求用户授予您访问所需数据的权限。
  3. 您的应用会从授权服务器获取经过授权的请求令牌。
  4. 您将已授权的请求令牌换成访问令牌。
  5. 您可以使用访问令牌向 Google 的服务访问服务器请求数据。

当您的应用最初请求访问用户数据时，Google 会向您的应用发出未经授权的请求令牌。

如果用户尚未登录，Google 会提示用户登录。然后，Google 会显示一个授权页面，供用户查看您的应用正在请求访问哪些 Google 服务数据。

如果用户批准了您的应用的访问请求，Google 就会发出已授权的请求令牌。每个请求令牌的有效期仅为 1 小时。只有经过授权的请求令牌才能换取访问令牌，并且每个授权请求令牌只能进行一次此交换。

默认情况下，访问令牌是长期存在的。每个访问令牌都特定于原始授权请求中指定的用户帐号，仅授予对该请求中指定的服务的访问权限。您的应用应以安全的方式存储访问令牌，因为只有对用户数据进行所有访问都需要该访问令牌。

准备使用 OAuth

在将您的应用设置为通过 OAuth 使用 Google 授权服务之前，您必须完成以下任务。

决定是否注册您的 Web 应用

为了进一步提高用户的数据安全性，您可以选择向 Google 注册您的 Web 应用，并使用已注册的安全证书对您的请求进行签名。某些 Google 数据 API 的 Feed 仅适用于已注册的应用。请参阅您感兴趣的 Google 数据 API 的文档，确定该 API 是否仅适用于注册的应用。

您的应用必须对所发出的每个 OAuth 请求进行签名。如果您选择使用 RSA-SHA1 签名对请求进行签名，则必须在注册过程中上传安全证书。

或者，您可以使用 HMAC-SHA1 签名对请求进行签名。HMAC-SHA1 签名不需要证书。Google 会生成一个 OAuth consumer secret 值，该值在您注册后显示在域名注册页面上。

如需详细了解注册流程，请参阅注册 Web 应用。

确定应用将访问的数据的范围

每项 Google 服务都对其通过 Google Data API 允许的访问权限设置限制。此访问权限以范围值表示。某些服务提供了各种范围值，允许用户选择哪些应用应有权访问哪些数据。如需了解您要访问的 Google 服务的可用范围值，请参阅该服务的文档。

一般情况下，您应针对包含您所需数据的最小范围请求令牌。例如，如果您的应用需要访问用户的“所有日历”Feed，则应请求范围 http://www.google.com/calendar/feeds/default/allcalendars/full 的令牌。

设置 OAuth 令牌管理机制

为用户数据获取 OAuth 访问令牌时，您必须使用该访问令牌代表用户将来与指定的 Google 服务进行的所有互动。

您的应用应安全地管理令牌存储，包括跟踪每个令牌均有效的 Google 服务。 如果您需要访问多项 Google 服务，可以获取多个访问令牌，但在任何情况下不能超过一位用户和应用的访问令牌不超过 10 个。

如果您的应用支持多个用户帐号，您必须跟踪每个令牌关联的哪个帐号。 每个 OAuth 令牌都特定于授权用户。您的应用必须能够将令牌与正确的用户相关联。管理此问题的一种方式是在发出令牌请求之前向用户发出 Cookie。用户授予对所请求数据的访问权限后，Google 会发送已授权的请求令牌，并将用户重定向到您的应用。然后，您可以使用应用的 Cookie 将令牌与正确的用户相关联。

设置请求访问 Google 服务的机制

发送到 Google 服务的每个请求都必须进行签名，并且必须包含有效的 OAuth 访问令牌。通常，每个请求都是以 HTTP GET 请求的形式发出的，标头中包含访问令牌和签名。写入新数据的请求应使用 HTTP POST。

如需详细了解每个 Google Data API 的正确请求格式，请参阅该 API 的文档。

实现 OpenID（可选）

如果您要实现 OpenID 以进行用户身份验证，请考虑使用混合协议将这两个过程结合使用。使用 OpenID+OAuth 时，获取请求令牌并向其授权的任务将作为 OpenID 请求的一部分通过 OAuth 扩展程序进行处理。与 OAuthGetRequestToken 一样，这些扩展程序用于标识要访问的 Google 服务。对 OpenID 请求的成功响应包含经过授权的请求令牌。收到此令牌后，请使用 OAuthGetAccessToken 将其转换为访问令牌。

使用 OAuth 令牌

如需使用 OAuth，您的应用必须生成格式正确的签名令牌请求调用，并按以下顺序处理响应：

  1. 获取未经授权的请求令牌 (OAuthGetRequestToken)
  2. 为请求令牌 (OAuthAuthorizeToken) 授权
  3. 用已授权的请求令牌交换访问令牌 (OAuthGetAccessToken)

无论您的应用是否已注册，所有 OAuth 请求都必须签名。如需了解详情，请参阅对 OAuth 请求进行签名。

您可以尝试在 OAuth 园地中请求和接收授权令牌。

如需查看详细文档，请参阅 OAuth API 参考文档。

设置回调网址

您可以在 OAuthGetRequestToken 请求中指定 oauth_callback 的值，以确定 Google 在用户授权访问请求后将其重定向到何处。回调网址可以包含查询参数。重定向将包含相同的查询参数，以及您的应用必须能够解析的授权请求令牌。

例如，在支持多种语言时，您可以添加一个查询参数，用于标识用户正在查看的应用版本。oauth_callback 值“http://www.yoursite.com/检索令牌?lang=de”会导致重定向“http://www.yoursite.com/检索令牌?lang=de&oauth_token=DQAADKEDE”。解析令牌和语言参数可确保将用户重定向回网站的正确版本。

如果未添加 oauth_callback 参数，Google 会在授权您的访问权限请求后，将用户引导至显示验证编号的网页（请参阅示例）。用户必须先手动返回您的应用并输入验证编号，然后您才能获得授权请求令牌。

向用户标识您的应用

在请求用户同意时，Google 通常会显示应用的名称（查看示例）。

如果您的应用未注册，请在 OAuthGetRequestToken 请求中使用 xoauth_displayname 参数来指定您的应用名称。如果未指定该参数，Google 会显示 oauth_callback 参数提供的网址的域名。如果未提供回调网址，Google 会显示字符串“anonymous”。

如果您的应用已注册，请勿设置此参数。默认情况下，Google 会显示注册期间指定的显示名称。如果您在 OAuthGetRequestToken 请求中设置了显示名称，Google 将使用此信息而非您注册的显示名称，并包含一条消息，指出应用的身份无法验证。

注意：如需在 OAuth Playground 中设置 xoauth_displayname 参数，请先勾选“高级”复选框，然后再提取请求令牌。

使用 Google Apps 网域

如果您的应用是针对托管 Google 帐号网域中的用户而设计的，请考虑在授权令牌时使用 hd 参数。如需详细了解 hd 参数，请参阅处理具有多个帐号的用户。

详细了解 OAuth

如需详细了解 Google 的 OAuth 实现方法（包括如何注册您的应用和构建必要的 OAuth 参数），请参阅下面列出的其他资源：

返回页首

将 OAuth 用于已安装应用

所有 Google Data API 均支持 OAuth，OAuth 是一种用于授权在应用中使用数据的开放标准。已安装应用无需向 Google 注册即可使用 OAuth。

OAuth 授权流程

OAuth 授权流程涉及您的应用、Google 授权服务器和最终用户之间的一系列互动。

基本流程如下：

  1. 您的应用会请求访问权限，并从 Google 的授权服务器获取未经授权的请求令牌。
  2. Google 会要求用户授予您访问所需数据的权限。
  3. 您的应用会从授权服务器获取经过授权的请求令牌。
  4. 您将已授权的请求令牌换成访问令牌。
  5. 您可以使用访问令牌向 Google 的服务访问服务器请求数据。

当您的应用最初请求访问用户数据时，Google 会向您的应用发出未经授权的请求令牌。

如果用户尚未登录，Google 会提示用户登录。然后，Google 会显示一个授权页面，供用户查看您的应用正在请求访问哪些 Google 服务数据。

如果用户批准了您的应用的访问请求，Google 就会发出已授权的请求令牌。每个请求令牌的有效期仅为 1 小时。只有经过授权的请求令牌才能换取访问令牌，并且每个授权请求令牌只能进行一次此交换。

OAuth 支持使用未注册模式的已安装应用。由于获取授权请求令牌的方法有很多种，因此即使 OAuth 安装在没有网络浏览器的情况下，应用也可以使用 OAuth 对该应用进行授权。

默认情况下，访问令牌是长期存在的。每个访问令牌都特定于原始授权请求中指定的用户帐号，仅授予对该请求中指定的服务的访问权限。您的应用应以安全的方式存储访问令牌，因为只有对用户数据进行所有访问都需要该访问令牌。

准备使用 OAuth

在将您的应用设置为通过 OAuth 使用 Google 授权服务之前，您必须完成以下任务。

确定应用将访问的数据的范围

每项 Google 服务都对其通过 Google Data API 允许的访问权限设置限制。此访问权限以范围值表示。某些服务提供了各种范围值，允许用户选择哪些应用应有权访问哪些数据。如需了解您要访问的 Google 服务的可用范围值，请参阅该服务的文档。

一般情况下，您应针对包含您所需数据的最小范围请求令牌。例如，如果您的应用需要访问用户的“所有日历”Feed，则应请求范围 http://www.google.com/calendar/feeds/default/allcalendars/full 的令牌。

设置 OAuth 令牌管理机制

为用户数据获取 OAuth 访问令牌时，您必须使用该访问令牌代表用户将来与指定的 Google 服务进行的所有互动。

您的应用应安全地管理令牌存储，包括跟踪每个令牌均有效的 Google 服务。

如果您的应用支持多个用户帐号，您必须跟踪每个令牌关联的哪个帐号。

设置请求访问 Google 服务的机制

发送到 Google 服务的每个请求都必须进行签名，并且必须包含有效的 OAuth 访问令牌。通常，每个请求都是以 HTTP GET 请求的形式发出的，标头中包含访问令牌和签名。写入新数据的请求应使用 HTTP POST。

如需详细了解每个 Google Data API 的正确请求格式，请参阅该 API 的文档。

使用 OAuth 令牌

如需使用 OAuth，您的应用必须生成格式正确的签名令牌请求调用，并按以下顺序处理响应：

  1. 获取未经授权的请求令牌 (OAuthGetRequestToken)
  2. 为请求令牌 (OAuthAuthorizeToken) 授权
  3. 用已授权的请求令牌交换访问令牌 (OAuthGetAccessToken)

无论您的应用是否已注册，所有 OAuth 请求都必须签名。如需了解详情，请参阅对 OAuth 请求进行签名。 安装的应用应按照针对未注册应用的说明执行操作。

您可以尝试在 OAuth 园地中请求和接收授权令牌。

如需查看详细文档，请参阅 OAuth API 参考文档。

向用户标识您的应用

在请求用户同意时，Google 通常会显示应用的名称（查看示例）。

在 OAuthGetRequestToken 请求中使用 xoauth_displayname 参数来指定应用的名称。如果未指定该参数，Google 会显示 oauth_callback 参数提供的网址的域名。如果未提供回调网址，Google 会显示字符串“anonymous”。

注意：如需在 OAuth Playground 中设置 xoauth_displayname 参数，请先勾选“高级”复选框，然后再提取请求令牌。

启动网络浏览器

在 OAuth 授权流程中，您的应用必须发出 OAuthAuthorizeToken 请求。然后，用户必须登录到 Google 网页，并对您的应用的访问权限请求进行授权。

  • 大多数应用都应该使用自动检测模式
  • 设备模式应用于无法启动完整网络浏览器的应用。
  • 开发模式只能在早期开发期间使用。

自动检测模式

如果可能，您的应用应启动浏览器窗口并发出 OAuthAuthorizeToken 请求，以打开 Google 页面。当 Google 返回经过授权的令牌时，您的应用应检测到此令牌并从网络浏览器中重新获得焦点。

此模式要求您提供一个授权网址，用户在授权访问请求后将被重定向到该网址。此网址必须作为 OAuthGetRequestToken 请求的 oauth_callback 参数和 OAuthGetAccessToken 请求的 verifier 参数提供。

为了改善用户体验，您的应用应尝试在用户被重定向至此网址时自动检测，并立即将自己置于前台，并发出 OAuthGetAccessToken 请求以完成 OAuth 流程。

如需了解详情和最佳做法，请参阅自动检测审批。

如果您的应用无法检测到用户被重定向到回调网址，或者无法将自己调入前台，该回调网址应显示一个页面，其中介绍了如何将您的应用调到前台以及如何在应用中发起 OAuthGetAccessToken 请求。

设备模式

如果您的应用无法启动完整网络浏览器，则富客户端设备也可以在不使用网络浏览器的情况下进行授权。

开发者可以使用此模式设置一个网站，用户可以在这个网站上授权访问请求。获得授权后，系统会向用户提供一个由 Google 生成的代码，并将其重定向到开发者的网站。此网站应向用户说明如何将代码输入到设备中以完成授权流程。

开发模式

建议仅在应用的早期开发期间使用此模式。

与在自动检测模式下一样，您的应用必须启动浏览器，并且用户必须授权您的请求。不过，您不必为回调网址创建网页，而是可以将 oauth_callback 参数的值设为 "oob"（带外）。

在这种情况下，用户授权您的请求后，Google 会将用户定向到显示验证号码的 Google 帐号页面（请参阅示例）。

用户必须返回您的应用并输入验证编号，然后您才能发出 OAuthGetAccessToken 请求。

详细了解 OAuth

如需详细了解 Google 的 OAuth 实现方法（包括如何注册您的应用和构建必要的 OAuth 参数），请参阅下面列出的其他资源：

返回页首

使用 AuthSub 进行授权

AuthSub 是 Google 的一个专有授权 API，可替代大多数 Google API 的 OAuth。您应尽可能避免使用 AuthSub。如果您已经有使用 AuthSub 的应用，则应迁移到 OAuth 或混合协议。

AuthSub 授权流程

AuthSub 授权涉及 Web 应用、Google 服务和用户这三个实体之间的一系列互动。下图说明了序列：

授权流程

  1. 当 Web 应用需要访问用户的 Google 服务时，它会对 Google 的授权代理服务进行 AuthSub 调用。
  2. 授权服务通过提供访问请求页面进行响应。此由 Google 管理的页面会提示用户授予/拒绝对其 Google 服务的访问权限。系统可能会先要求用户登录自己的帐号。
  3. 用户决定是授予还是拒绝 Web 应用的访问权限。如果用户拒绝授予访问权限，则会定向到 Google 页面，而不是 Web 应用。
  4. 如果用户授予访问权限，授权服务会将用户重定向回 Web 应用。重定向包含一个适用于一次性授权的授权令牌；该令牌可以交换为长期令牌。
  5. Web 应用通过授权令牌与 Google 服务通信，并使用授权令牌充当用户的代理。
  6. 如果 Google 服务识别出令牌，就会提供所请求的数据。

使用 AuthSub

将 AuthSub 整合到您的 Web 应用中需要以下任务：

  1. 决定是否注册您的 Web 应用。

    注册的 Web 应用具有 Google 认可的优点；在 Google 登录页面上向用户显示的标准注意事项已修改或省略。此外，注册的 Web 应用由描述性名称标识，而不只是调用网址。请注意，某些 Google 服务仅允许对未注册的 Web 应用进行有限访问。如果您选择报名，请按照此自动注册流程操作。

    注册时，您还可以提供安全证书和密钥。具有记录证书的已注册 Web 应用能够获取安全令牌，以便在向 Google 服务请求数据时使用。（如有必要，它们也可以使用非安全令牌。）

  2. 确定要使用的令牌类型以及管理方式。

    从 Google 收到的授权令牌旨在用于该用户今后与指定 Google 服务之间的所有互动。您选择要使用的令牌类型（一次性或会话）将取决于您的 Web 应用与 Google 服务之间的互动类型。例如，如果互动是一次性或罕见事件，一次性令牌可能就足够了。

    如果您选择获取会话令牌并定期使用它们来访问 Google 服务，您的 Web 应用将需要管理令牌存储空间，包括跟踪令牌有效的用户和 Google 服务。Google 帐号未设置为管理大量令牌，实际上，任何时候，每个用户、每个 Web 应用的有效令牌都不能超过 10 个。此限制允许 Web 应用在必要时获取多个令牌以涵盖不同的服务；它不支持每次 Web 应用需要访问 Google 服务时都获取新令牌。如果您决定存储会话令牌，则相应令牌应像存储在服务器上的任何其他敏感信息一样安全。

    或者，只要您设置令牌撤消机制，就可以选择定期获取新的令牌。您的应用需要先撤消现有令牌，然后才能请求其他令牌。在这种情况下，每次请求新令牌时，系统都会要求用户登录并授予访问权限。

  3. 确定访问 Google 服务所需的范围。

    每项 Google 服务都会确定允许多少访问权限以及哪些类型的访问权限。此访问权限以范围值表示。服务范围可以是用来标识整个服务的简单网址，也可以指定更为严格的访问权限。某些服务会严重限制访问权限，例如允许对受限信息进行只读访问。如需获取您想访问的 Google 服务的允许范围，请参阅该服务的文档。您应尽可能请求最严格的令牌。例如，如果您要尝试使用 Gmail 的 Atom Feed 功能，请使用范围“http://www.google.com/calendar/feed/”，而不是“http://www.google.com/calendar/”。对于范围较大的请求，Google 服务的限制性更强。

  4. 设置请求和接收授权令牌的机制。

    该机制必须生成格式正确的 AuthSubRequest 调用，包括指定适当的 next 和范围网址值（在第 3 步中确定）。如果您使用的是安全令牌和/或管理会话令牌，请求还必须包含这些变量的值。

    下一个网址可包含查询参数。例如，在支持多种语言时，请添加可标识用户正在查看的 Web 应用版本的查询参数。next 值 http://www.yoursite.com/Retrievetoken?Lang=de 会导致重定向 http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE。解析令牌和 lang 参数可确保将用户重定向回正确的网站版本。

    在某些情况下，当用户被要求向 Google 帐号网站授予访问权限时，使用 hd 参数有助于简化用户体验。在大多数情况下，完成此过程很简单，只需登录其帐号并选择是否授予访问权限即可。不过，拥有多个 Google 帐号（常规 Gmail 帐号和/或一个或多个 Google Apps 托管帐号）的用户可能需要执行额外的“通用登录”流程，以识别他们想要访问的帐号。如果您的应用是针对某个特定的受管理域名设计的，您可以使用此参数来标识该网域，从而省去这些额外的步骤。如果应用访问的服务在托管帐号中不可用，您也可以使用 hd 参数。将值设置为“default”会将授权范围限制为常规帐号。设置 hd 值后，Google 会自动选择正确的帐号进行授权。

    令牌机制必须能够解析从 Google 收到的重定向（其中包含一次性令牌），并对该令牌执行操作。由于授权令牌特定于用户，因此您的应用必须能够将令牌与其用户相关联。首选方法是在发出令牌请求之前向用户发送 Cookie。然后，当 Google 使用附加令牌将用户重定向回您的网站时，您的应用可以读取 Cookie 并将令牌与正确的用户标识相关联。

  5. 设置请求会话令牌的机制，并存储或撤消这些令牌（如果相关）。

    根据您在第 2 步中所做的令牌管理决策，您可能需要创建机制来撤消和撤消会话令牌（AuthSubSessionToken 和 AuthSubRevokeToken）。如需测试会话和撤消机制，请使用 AuthSubTokenInfo，用于指明给定令牌是否有效。如果存储令牌，应用必须同时跟踪用户 ID 和令牌涵盖的服务（范围）。

  6. 设置请求 Google 服务访问权限的机制。

    如需了解正确的请求格式，请参阅 Google 服务的文档。向 Google 服务发出的所有请求都必须包含有效的授权令牌。通常，向 Google 服务发出的请求采用 HTTP GET（或者，如果写入了新数据，则为 POST），具体形式为请求标头中引用的令牌。

    请求标头应采用以下格式：

    Authorization: AuthSub token="token"

    其中 token 是为响应 AuthSub 请求而从 Google 收到的授权令牌（一次性或会话）。如果令牌安全，则必须附带数字签名。如需查看相关说明和示例，请参阅“对请求进行签名”。

    以下示例展示了对 Google 日历 Feed 服务的调用的请求标头。此请求包含非安全令牌：

    GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

详细了解 AuthSub

有关 AuthSub 的信息，包括在 Google 中注册应用以及用一次性令牌交换会话令牌的详细说明，请参阅以下其他资源：

返回页首

使用 Paging 进行授权

StreetView 是 Google 的专有授权 API，可替代大多数 Google API 的 OAuth。您应尽量避免使用 Paging。如果您已经有使用 SRA 的应用，则应迁移到 OAuth 或混合协议。

针对已安装应用的身份验证：StreetView

使用 PWA 让您的用户可以在应用内登录他们的 Google 帐号。然后，应用程序会与 Google 联系并提供登录数据，并请求访问指定的 Google 数据 API。登录信息成功通过验证后，Google 便会返回一个令牌。您的应用每次请求访问用户的帐号时（例如获取或发布数据）都会使用该令牌。该令牌在设定的期限内有效，具体取决于您使用的任何 Google 服务。

注意：Google Data API 客户端库提供了一些帮助您在已安装的应用中使用 Paging 的方法。具体而言，您可以通过多种方法来获取身份验证令牌、处理人机识别系统质询、找回身份验证令牌以供日后使用，以及在每次请求中发送正确的 Authorization 标头。如果您使用了其中一个库，请参阅将 Paging 与 Google Data API 客户端库结合使用。

SRA 授权流程

使用 Paging 授权涉及三个实体之间的一系列互动：已安装的应用、Google 服务和用户。下图说明了序列：

授权流程

  1. 当第三方应用需要访问用户的 Google 服务时，它会检索用户的登录名和密码。
  2. 然后，第三方应用调用 Google 的授权服务。
  3. 如果 Google 授权服务认为需要进行额外的审查，它会以人机识别系统图片的网址形式返回包含人机识别系统令牌和质询的失败响应。
  4. 如果收到人机识别系统质询，第三方应用就会向用户显示人机识别系统的图片，并征求用户的回答。
  5. 如果用户请求，则提交对人机识别系统质询的回答。
  6. 第三方应用发起新的 SRA 调用，这次是添加人机识别系统应答和令牌（通过失败响应接收）。
  7. 用户成功登录（无论是否通过人机识别系统质询）后，Google 授权服务会向应用返回一个令牌。
  8. 应用与 Google 服务联系，请求获取数据访问权限，并引用从 Google 授权服务收到的令牌。
  9. 如果 Google 服务识别出令牌，就会提供所请求的数据访问权限。

使用 Paging

在已安装的应用中使用此界面，以编程方式访问用户的 Google 帐号。从用户那里收集登录信息后，请调用 StreetView 来请求访问用户的帐号。登录信息成功通过验证后，Google 会返回一个令牌。您的应用每次请求访问用户帐号时，都会引用该令牌。该令牌会在设定的一段时间内有效，该时长由您使用的 Google 服务决定。

将 Paging 并入您的应用需要以下任务：

  1. 创建界面元素，以捕获用户的登录数据。

    用户界面需要收集用户名（包括域名在内的电子邮件地址）和密码。 界面也应该能够使用从 Google 收到的网址（如有必要）显示人机识别系统图片，并征求用户的正确回答。理想情况下，如果用户需要注册新帐号或进行其他帐号维护，您的界面中将包含指向 Google 帐号登录页面（“https://www.google.com/accounts/Login”）的链接。

  2. 编写代码，以生成格式正确的 HTTPS POST ClientLogin 请求并将其传输。

    此代码需要包含处理人机识别系统质询的逻辑，并同时包含 logintoken 和 logincaptcha 参数。应用还应该能够检测用户何时省略了必需的信息（或在登录失败后重复错误的数据），并在没有发送多余请求的情况下显示错误。

  3. 处理来自 Google 的响应。

    登录请求有四种可能的响应：

    • 成功 (HTTP 200)
    • 失败 (HTTP 403)，并提供解释性错误代码
    • 请求无效，通常是因为请求格式不正确
    • 未通过人机识别系统验证

    成功响应包含标有“Auth”的授权令牌。此令牌必须包含在此帐号向 Google 服务发出的所有后续请求中。授权令牌应受到严格保护，不得提供给任何其他应用，因为它们表示对用户帐号的访问权限。令牌的时间限制因颁发令牌的服务而异。

    失败响应包括一个或多个错误代码，以及可向用户显示的错误消息的网址。请注意，ClientLogin 无法区分密码错误失败失败和用户名无法识别的情况（例如，用户尚未注册帐号）。您的应用需要视情况处理所有可能的错误消息。

    如果验证结果为人机识别系统验证失败，则表示 Google 出于任何原因已决定应采取额外的安全措施。此响应附有人机识别系统图片网址和代表特定人机识别系统质询的令牌。

  4. 处理来自 Google 的人机识别系统验证。

    如需处理质询，应用必须显示人机识别系统图片并征求用户的回答。如需显示人机识别系统图片，请使用失败响应返回的 CaptchaUrl 值，并在前面加上 Google 帐号网址作为前缀：http://www.google.com/accounts/。用户回答问题后，应用应重新发送登录请求，这次需要输入人机识别系统令牌 (logintoken) 和用户的回答 (logincaptcha)。Google 会在验证用户对帐号的访问权限之前验证用户的回答。

    如果开发者不想管理获取和传输用户人机识别系统响应的流程，有一种替代方案。为了响应人机识别系统质询，该应用可以将用户定向到 Google 托管的页面：“https://www.google.com/accounts/DisplayUnlockCaptcha”。用户成功响应验证后，Google 服务器就会信任所用计算机。然后，应用可以重新发送原始登录请求以获取授权令牌。

    5. 注意：在发出人机识别系统质询之前，Google 不会验证登录尝试。这意味着即使在人机识别系统验证后，登录尝试也可能会失败。

* 人机识别系统是卡内基梅隆大学的商标

返回页首

小工具身份验证

OAuth 代理

如果您使用标准 Gadgets API 构建小工具，则可以利用以下小工具平台的功能（称为 OAuth 代理）访问 Google Data API。OAuth（如上文所述）是一种身份验证标准，允许用户在小工具托管服务（如 iGoogle、MySpace 或 Orkut）中访问他们的私人数据，或与其他网站或小工具共享自己的数据。OAuth 代理通过隐藏 OAuth 的许多身份验证详细信息，让小工具开发者可以更轻松地进行开发。代理基于名为 Shindig 的开源项目，该项目是小工具规范的实现。

注意：只有使用 gadgets.* API 并在 OpenSocial 容器中运行的小工具才支持 OAuth 代理。旧版小工具 API 不支持此功能。

身份验证流程

您的小工具必须先获取 OAuth 令牌，然后才能访问用户数据。OAuth 代理会为您管理身份验证流程。用户首次安装您的小工具时，会发生以下过程：

  1. 您的小工具是第一次加载，并尝试使用某个 Google 数据 API 访问用户数据。
  2. 由于用户未授予访问权限，因此请求失败。响应对象包含 OAuth 审批页面的网址（位于 response.oauthApprovalUrl 中）。您的小工具应提供一种方法来使用该网址启动新窗口。
  3. 在审批页面上，用户选择授予或拒绝访问您的小工具的权限。如果成功，系统会将用户转到您指定的 oauth_callback 页面。为了提供最佳用户体验，请使用 http://oauth.gmodules.com/gadgets/oauthcallback。
  4. 接下来，用户会关闭弹出式窗口。要通知您的小工具用户已批准，您可以使用弹出式窗口处理程序检测关闭关闭窗口。或者，您的小工具可以显示一个链接（例如“我已批准的访问权限”）以供用户在该窗口关闭后点击。
  5. 您的小工具通过重新请求用户的数据来尝试再次访问 Google Data API。此尝试成功。
  6. 您的小工具已经过身份验证，可以开始正常运行。

小工具设置

要访问一个或多个 Google 数据 API，首先需要告知小工具使用 OAuth 作为身份验证方法。在小工具的 XML 的 <ModulePrefs> 部分添加一个 <OAuth> 元素：

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

在本部分中，请仅更改以下查询参数：

scope
请求网址中必需的参数。您的小工具可以访问此参数中使用的 scope 中的数据。在此示例中，该小工具可以访问 Blogger 和 Google 日历数据。正如示例所示，小工具可以请求单个范围或多个范围的数据。
oauth_callback
“授权网址”中的可选参数。在用户批准数据访问后，OAuth 审批页面会重定向到此网址。您应将此参数设置为 http://oauth.gmodules.com/gadgets/oauthcallback，以便在用户安装您的小工具时提供最佳用户体验。该网页提供一段 JavaScript 代码，用于自动关闭弹出式窗口。或者，您可以将此参数设置为指向您自己的“已批准”页面，也可以直接将该参数留空。

访问经过身份验证的 Google Data API Feed

在您的小工具对用户进行身份验证后，使用 Google 数据 API JavaScript 客户端库即可轻松访问 Google 数据 API。如需了解如何在 OAuth 代理中使用该库，请参阅使用 JavaScript 客户端库。

关于小工具的更多信息

如需关于如何创建 Google Data API 小工具的完整信息（包括有关 OAuth 代理的详细信息、入门文章以及 gadgets.* 规范），请参阅以下其他资源：

返回页首