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

警告：此页面介绍的是 Google 的旧版 API（即 Google Data API），仅适用于Google Data API 目录中列出的 API，其中许多 API 已被更新的 API 取代。如需了解特定新 API，请参阅相应新 API 的文档。如需了解如何使用较新的 API 授权请求，请参阅 Google 账号身份验证和授权。

第三方应用通常需要对用户的 Google 账号进行有限访问，才能执行某些类型的活动。为确保用户数据不会被滥用，所有访问请求都必须获得账号持有人的批准。访问权限控制包含两个组成部分：身份验证和授权。

身份验证服务可让用户使用 Google 账号登录您的应用。

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

身份验证和授权服务通常统称为 auth。

通过 Google API 的身份验证和授权，第三方应用可以有限地访问用户 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 Accounts API 的讨论。

OAuth - Web 应用和已安装应用的授权

许多 Google 服务都允许第三方访问用户生成的数据（例如日历或文档数据），前提是用户已授权访问。借助此功能，用户可以在 Google 应用和第三方应用之间分享和交换数据，以实现各种目的。

Google 支持两种版本的 OAuth，用于获取对用户 Google 数据的授权访问权限：OAuth 1.0 和 OAuth 2.0，这两种版本都允许网络应用和已安装的应用访问用户数据。

针对 Web 应用和已安装应用的 OAuth 2.0

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

适用于 Web 应用的 OAuth 1.0

需要获得授权才能访问与 Google 账号或 Google 应用账号相关联的数据的 Web 应用可以使用 Google 的 OAuth API 实现。如需全面了解如何为基于 Web 的应用实现 OAuth（包括示例），请参阅 OAuth for Web Apps 指南，或参阅本文档中的概览。

针对已安装应用的 OAuth 1.0

安装在用户计算机和移动设备上的应用可以使用 OAuth 授权访问与 Google 账号相关联的数据。如需详细了解如何为已安装的应用实现 OAuth，请参阅 OAuth for Installed Applications 指南，或参阅本文档中的概览。

将 OAuth 与 Web 应用搭配使用

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

Google Data API 客户端库提供了一些方法，可帮助您在 Web 应用中使用 OAuth。具体而言，有用于构建请求令牌、授权请求令牌以及将授权的请求令牌交换为访问令牌的方法。这些库还会在向 Google Data 服务发出请求时处理必要的签名算法。如需查看有关如何将 OAuth 与 Google Data API 客户端库搭配使用的丰富示例，请参阅将 OAuth 与 Google Data API 客户端库搭配使用。

OAuth 授权流程

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

从基本层面来看，该流程如下：

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

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

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

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

默认情况下，访问令牌的有效期较长。每个访问令牌都特定于原始授权请求中指定的用户账号，并且仅授予对该请求中指定服务的访问权限。您的应用应安全地存储访问令牌，因为访问用户的所有数据都需要此令牌。

准备使用 OAuth

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

确定是否注册 Web 应用

为了让用户更加放心地使用您的 Web 应用，您可以选择向 Google 注册您的 Web 应用，并使用注册的安全证书对请求进行签名。部分 Google Data API Feed 仅适用于已注册的应用。请参阅您感兴趣的 Google Data 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，您的应用必须生成格式正确的签名令牌请求调用，并处理响应，以完成以下序列：

获取未经授权的请求令牌 (OAuthGetRequestToken)
授权请求令牌 (OAuthAuthorizeToken)
将授权的请求令牌交换为访问令牌 (OAuthGetAccessToken)

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

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

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

设置回调网址

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

例如，在支持多种语言时，您可以添加一个查询参数来标识用户正在查看的应用版本。如果 oauth_callback 值为“http://www.yoursite.com/Retrievetoken?Lang=de”，则重定向网址为“http://www.yoursite.com/Retrievetoken?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 应用网域

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

详细了解 OAuth

如需详细了解 Google 的 OAuth 实现，包括如何注册应用和构建必要的 OAuth 参数，请参阅以下其他资源：

将 OAuth 与 Google Data API 客户端库搭配使用
文章：将 OAuth 与 Google Data API 搭配使用，其中包含 OAuth Playground 的说明，这是一个用于试用 OAuth 的互动式工具。
适用于 Web 应用的 OAuth（完整文档）
基于 Web 的应用的注册
生成密钥和证书
OAuth 规范

返回页首

将 OAuth 与已安装的应用搭配使用

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

OAuth 授权流程

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

从基本层面来看，该流程如下：

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

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

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

OAuth 支持使用未注册模式的已安装应用。由于有多种方法可以获取授权的请求令牌，因此即使应用安装到的设备没有 Web 浏览器，您的应用也可以使用 OAuth 来授权应用。

准备使用 OAuth

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

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

设置用于管理 OAuth 令牌的机制

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

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

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

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

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

使用 OAuth 令牌

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

获取未经授权的请求令牌 (OAuthGetRequestToken)
授权请求令牌 (OAuthAuthorizeToken)
将授权的请求令牌交换为访问令牌 (OAuthGetAccessToken)

无论您的应用是否已注册，所有 OAuth 请求都必须经过签名。如需了解详情，请参阅签署 OAuth 请求。已安装的应用应遵循未注册应用的说明。

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

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

向用户标识您的应用

Google 通常会在向用户请求访问权限时显示应用的名称（请参阅示例）。

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

注意：如需在 OAuth Playground 中设置 xoauth_displayname 参数，请在获取请求令牌之前选中“高级”框。

启动网络浏览器

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

大多数应用都应使用 AutoDetect 模式
设备模式应适用于无法启动完整网络浏览器的应用。
开发模式应仅在早期开发阶段使用。

自动检测模式

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

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

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

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

如果您的应用无法自动检测到用户何时重定向到回调网址，或者无法将自身置于前台，则回调网址应显示一个页面，其中说明了如何将应用置于前台，以及如何从应用内发起 OAuthGetAccessToken 请求。

设备模式

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

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

开发模式

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

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

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

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

详细了解 OAuth

如需详细了解 Google 的 OAuth 实现，包括如何注册应用和构建必要的 OAuth 参数，请参阅以下其他资源：

将 OAuth 与 Google Data API 客户端库搭配使用
文章：将 OAuth 与 Google Data API 搭配使用，其中包含 OAuth Playground 的说明，这是一个用于试用 OAuth 的互动式工具。
适用于已安装应用的 OAuth（完整文档）
生成密钥和证书
OAuth 规范

返回页首

使用 AuthSub 进行授权

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

AuthSub 授权流程

使用 AuthSub 进行授权涉及三个实体（Web 应用、Google 服务和用户）之间的一系列互动。下图展示了这一顺序：

授权流程

当 Web 应用需要访问用户的 Google 服务时，它会向 Google 的授权代理服务发出 AuthSub 调用。
授权服务会通过提供“访问权限申请”页面来做出响应。此页面由 Google 管理，会提示用户授予/拒绝访问其 Google 服务的权限。系统可能会先要求用户登录其账号。
用户决定是否授予对 Web 应用的访问权限。如果用户拒绝授予访问权限，系统会将用户定向到 Google 页面，而不是返回到 Web 应用。
如果用户授予访问权限，授权服务会将用户重定向回 Web 应用。重定向包含一个仅可使用一次的授权令牌；该令牌可交换为长期有效的令牌。
Web 应用会使用授权令牌作为用户的代理，向 Google 服务发送请求。
如果 Google 服务识别出该令牌，就会提供所请求的数据。

使用 AuthSub

将 AuthSub 纳入您的 Web 应用需要执行以下任务：

决定是否注册 Web 应用。
注册的 Web 应用可被 Google 识别，因此 Google 登录页面上向用户显示的常见警告会进行修改或省略。此外，注册的网络应用会使用描述性名称（而不仅仅是调用网址）进行标识。请注意，某些 Google 服务仅允许未注册的网络应用进行有限的访问。如果您选择注册，请使用此自动化注册流程。

如果您注册，还可以提供安全证书和密钥。已注册且已备案证书的网络应用能够获取安全令牌，以便在从 Google 服务请求数据时使用。（如有必要，他们也可以使用不安全的令牌。）
确定要使用的令牌类型以及如何管理这些令牌。
从 Google 收到的授权令牌旨在用于该用户与指定 Google 服务的所有未来互动。您选择使用的令牌类型（一次性令牌或会话令牌）取决于您的 Web 应用将与 Google 服务进行哪种类型的互动。例如，如果互动是一次性或极少发生的事件，则一次性令牌可能就足够了。

如果您选择获取会话令牌并定期使用它们来访问 Google 服务，您的 Web 应用将需要管理令牌存储，包括跟踪令牌对哪个用户和 Google 服务有效。Google 账号并非旨在管理大量令牌，事实上，它不允许任何时候有超过 10 个有效令牌（每个用户，每个 Web 应用）处于未完成状态。此限制允许 Web 应用获取多个令牌来涵盖不同的服务（如有必要）；但不支持在每次 Web 应用需要访问 Google 服务时都获取新令牌。如果您决定存储会话令牌，则应像对待服务器上存储的任何其他敏感信息一样，妥善保管这些令牌。

或者，您也可以选择定期获取新令牌，前提是您已设置令牌撤消机制。您的应用需要先撤消现有令牌，然后才能请求另一个令牌。在这种情况下，用户每次请求新令牌时都需要登录并授予访问权限。
确定要访问的 Google 服务所需的范围。
每项 Google 服务都会确定允许的访问权限量和类型。此访问权限以范围值的形式表示。服务的范围可以是标识整个服务的简单网址，也可以指定更受限的访问权限。某些服务会严格限制访问权限，例如仅允许对有限的信息进行只读访问。如需获取您要访问的 Google 服务的允许范围，请参阅相应服务的文档。您应尽可能请求范围最窄的令牌。例如，如果尝试访问 Gmail 的 Atom Feed 功能，请使用“http://www.google.com/calendar/feeds/”作用域，而不是“http://www.google.com/calendar/”。Google 服务对大范围请求的限制要严格得多。
设置用于请求和接收授权令牌的机制。
该机制必须生成格式正确的 AuthSubRequest 调用，包括指定适当的 next 和 scope 网址值（在第 3 步中确定）。如果您使用的是安全令牌和/或管理会话令牌，则请求还必须包含这些变量的值。

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

在某些情况下，使用 hd 参数有助于简化用户在 Google 账号网站上被要求授予访问权限时的体验。在大多数情况下，该流程非常简单，只需登录账号并选择是否授予访问权限即可。不过，如果用户有多个 Google 账号（一个常规 Gmail 账号和/或一个或多个 Google 应用托管账号），可能需要遵循额外的“通用登录”流程来指明他们希望访问哪个账号。如果您的应用是为某个特定的受管理网域设计的，您可以使用此参数来标识该网域，从而省去这些额外的步骤。如果您的应用访问托管账号中未提供的服务，您还可以使用 hd 参数 - 将该参数的值设置为“default”会将授权限制为仅限常规账号。设置 hd 值后，Google 会自动选择正确的账号进行授权。

令牌机制必须能够解析从 Google 收到的重定向（其中包含一次性令牌），并根据该令牌采取行动。由于授权令牌是特定于用户的，因此您的应用必须能够将令牌与其用户相关联。首选方法是在发出令牌请求之前向用户发放 Cookie。然后，当 Google 将用户重定向回您的网站并附加令牌时，您的应用可以读取 Cookie 并将令牌与正确的用户标识相关联。
设置用于请求会话令牌并存储或撤消会话令牌的机制（如果相关）。
根据您在第 2 步中做出的令牌管理决策，您可能需要创建用于获取和撤消会话令牌（AuthSubSessionToken 和 AuthSubRevokeToken）的机制。如需测试会话和撤消机制，请使用 AuthSubTokenInfo，该方法可指示指定令牌是否有效。如果存储令牌，应用必须跟踪用户 ID 和令牌涵盖的服务（范围）。
设置用于请求访问 Google 服务的机制。
如需了解正确的请求格式，请参阅相应 Google 服务的文档。向 Google 服务发出的所有请求都必须包含有效的授权令牌。一般来说，对 Google 服务的请求采用 HTTP GET（或 POST，如果写入新数据）的形式，并在请求标头中引用令牌。

请求标头应采用以下格式：
```
Authorization: AuthSub token="token"
```
其中，token 是从 Google 收到的授权令牌（一次性令牌或会话令牌），用于响应 AuthSub 请求。如果令牌是安全的，则必须附带数字签名。如需查看相关说明和示例，请参阅“对请求进行签名”。

以下示例展示了对 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 注册应用以及详细说明如何将一次性令牌换成会话令牌，请参阅以下其他资源：

返回页首

使用 ClientLogin 进行授权

ClientLogin 是 Google 专有的授权 API，可作为 OAuth 的替代方案用于大多数 Google API。您应尽可能避免使用 ClientLogin。如果您已有使用 ClientLogin 的应用，则应迁移到 OAuth 或混合协议。

针对已安装的应用进行身份验证：ClientLogin

ClientLogin 可让用户从您的应用内登录其 Google 账号。然后，应用会使用登录数据与 Google 联系，并请求访问指定的 Google Data API。成功验证登录信息后，Google 会返回一个令牌，您的应用每次请求访问用户账号（例如获取或发布数据）时都会引用该令牌。令牌在设定的时间长度内保持有效状态，具体时长取决于您使用的 Google 服务。

注意：Google Data API 客户端库提供了一些方法，可帮助您在已安装的应用中使用 ClientLogin。具体而言，有用于获取身份验证令牌、处理 CAPTCHA 挑战、回忆身份验证令牌以供日后使用以及在每个请求中发送正确 Authorization 标头的方法。如果您使用的是其中一个库，请参阅将 ClientLogin 与 Google Data API 客户端库搭配使用。

ClientLogin 授权流程

使用 ClientLogin 进行授权涉及三个实体之间的一系列互动：已安装的应用、Google 服务和用户。下图展示了这一顺序：

授权流程

当第三方应用需要访问用户的 Google 服务时，它会检索用户的登录名和密码。
然后，第三方应用会向 Google 的授权服务发出 ClientLogin 调用。
如果 Google 授权服务认为有必要进行额外的审核，则会返回失败响应，其中包含 CAPTCHA 令牌和验证，以 CAPTCHA 图片的网址形式呈现。
如果收到人机识别系统验证，第三方应用会向用户显示人机识别系统图片，并征求用户的回答。
如果系统要求，用户需要提交人机识别系统验证的答案。
第三方应用会进行新的 ClientLogin 调用，这次会包含 CAPTCHA 答案和令牌（随失败响应一起收到）。
在登录尝试成功时（无论是否有人机识别系统验证），Google 授权服务都会向应用返回令牌。
应用与 Google 服务联系，请求访问数据，并引用从 Google 授权服务收到的令牌。
如果 Google 服务识别出该令牌，就会提供所请求的数据访问权限。

使用 ClientLogin

在已安装的应用中使用此接口，以通过编程方式访问用户的 Google 账号。从用户处收集登录信息后，调用 ClientLogin 以请求访问用户的账号。成功通过身份验证后，Google 会返回一个令牌，您的应用每次请求访问用户账号时都会引用该令牌。令牌在设定的时间段内保持有效状态，具体时长取决于您使用的 Google 服务。

将 ClientLogin 纳入应用需要完成以下任务：

创建一个界面元素，用于捕获用户输入的登录数据。
界面需要征求用户名（包括网域的电子邮件地址）和密码。如果需要，该界面还应能够使用从 Google 收到的网址显示 CAPTCHA 图片，并向用户征求正确答案。理想情况下，您的界面应包含指向 Google 账号登录页面（“https://www.google.com/accounts/Login”）的链接，以便用户在需要注册新账号或进行其他账号维护时使用。
编写代码以生成格式正确的 HTTPS POST ClientLogin 请求并传输该请求。
此代码需要包含用于处理人机识别系统验证的逻辑，并同时包含 logintoken 和 logincaptcha 参数。应用还应能够检测到用户何时遗漏了必需的信息，或者在登录失败后重复输入了错误的数据，并在不发送多余请求的情况下显示错误。
处理来自 Google 的回答。
登录请求可能有四种响应：
- 成功（HTTP 200）
- 失败（HTTP 403），并显示说明性错误代码
- 无效请求，通常是由于请求格式不正确所致
- 人机识别系统验证失败
成功响应包含一个标记为“Auth”的授权令牌。此令牌必须包含在针对相应账号向 Google 服务发出的所有后续请求中。授权令牌应妥善保管，不得提供给任何其他应用，因为它们代表着对用户账号的访问权限。令牌的时限因签发令牌的服务而异。

失败响应包含一个或多个错误代码以及一个包含可向用户显示的错误消息的网址。请注意，ClientLogin 不会区分因密码错误导致的失败和因用户名无法识别（例如，用户尚未注册账号）导致的失败。您的应用需要根据具体情况处理所有可能的错误消息。
如果失败响应中包含 CAPTCHA 质询，则表示 Google 已决定（无论出于何种原因）应采取额外的安全措施。此响应随附一个人机识别系统图片网址和一个表示特定人机识别系统验证的令牌。
处理来自 Google 的人机识别系统验证。
为了处理验证，应用必须显示人机识别系统图片并向用户征求答案。如需显示 CAPTCHA 图片，请使用失败响应返回的 CaptchaUrl 值，并在其前面加上 Google 账号网址：“http://www.google.com/accounts/”。用户提供答案后，应用应重新发送登录请求，这次应包含人机识别系统令牌 (logintoken) 和用户的答案 (logincaptcha)。Google 会先验证用户的答案，然后再授权用户访问相应账号。

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

注意：Google 不会在发出人机识别系统挑战之前验证登录尝试。这意味着，即使通过了 CAPTCHA 验证，登录尝试也可能会失败。

* CAPTCHA 是卡内基梅隆大学的商标

返回页首

针对微件的身份验证

OAuth 代理

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

注意：OAuth 代理仅适用于使用 gadgets.* API 并在 OpenSocial 容器中运行的微件。旧版信息中心应用 API 不支持此功能。

身份验证流程

您的信息中心应用必须先获取 OAuth 令牌，然后才能访问用户的数据。OAuth 代理会为您管理身份验证流程。用户首次安装您的信息中心时，系统会执行以下流程：

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

互动广告设置

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

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

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

有关小工具的更多信息

如需详细了解如何创建 Google Data API 桌面小工具，包括 OAuth 代理的详细信息、入门指南文章和 gadgets.* 规范，请参阅以下其他资源：

返回页首

Google 数据协议中的身份验证和授权 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

OAuth - Web 应用和已安装应用的授权

针对 Web 应用和已安装应用的 OAuth 2.0

适用于 Web 应用的 OAuth 1.0

针对已安装应用的 OAuth 1.0

将 OAuth 与 Web 应用搭配使用

OAuth 授权流程

准备使用 OAuth

确定是否注册 Web 应用

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

设置用于管理 OAuth 令牌的机制

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

实现 OpenID（可选）

使用 OAuth 令牌

设置回调网址

向用户标识您的应用

使用 Google 应用网域

详细了解 OAuth

将 OAuth 与已安装的应用搭配使用

OAuth 授权流程

准备使用 OAuth

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

设置用于管理 OAuth 令牌的机制

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

使用 OAuth 令牌

向用户标识您的应用

启动网络浏览器

自动检测模式

设备模式

开发模式

详细了解 OAuth

使用 AuthSub 进行授权

AuthSub 授权流程

使用 AuthSub

有关 AuthSub 的更多信息

使用 ClientLogin 进行授权

针对已安装的应用进行身份验证：ClientLogin

ClientLogin 授权流程

使用 ClientLogin

针对微件的身份验证

OAuth 代理

身份验证流程

互动广告设置

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

有关小工具的更多信息

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