适用于移动应用和桌面应用的 OAuth 2.0

本文档介绍了在手机、平板电脑和计算机上安装的应用如何使用 Google 的 OAuth 2.0 端点向 Google API 授予访问权限。

OAuth 2.0 允许用户与应用共享特定数据，同时保持用户名、密码和其他信息的私密性。例如，应用可以使用 OAuth 2.0 获得用户许可，将文件存储在他们的 Google 云端硬盘中。

已安装应用会分发到各个设备，并且假定这些应用无法保管密钥。当用户出现在应用上或应用在后台运行时，他们可以访问 Google API。

此授权流程类似于网络服务器应用所使用的授权流程。主要区别在于，已安装的应用必须打开系统浏览器并提供本地重定向 URI，以处理来自 Google 授权服务器的响应。

替代方案

对于移动应用，您可能希望在 Android 或 iOS 设备上使用 Google 登录功能。Google 登录客户端库会处理身份验证和用户授权，实现起来可能比此处介绍的较低级别协议更简单。

对于在不支持系统浏览器或具备有限输入功能的设备（例如电视、游戏机、相机或打印机）上运行的应用，请参阅适用于电视和设备的 OAuth 2.0 或在电视和受限输入设备上登录。

库和示例

我们建议您使用以下库和示例实现本文档中所述的 OAuth 2.0 流程：

• AppAuth for Android 库
• AppAuth for iOS 库
• OAuth for Apps：Windows 示例

前提条件

为您的项目启用 API

调用 Google API 的任何应用都需要在 API Console中启用这些 API。

如需为您的项目启用该 API，请按以下步骤操作：

1. Open the API Library （在 Google API Console中）。
2. If prompted, select a project, or create a new one.
3. API Library 列出了所有可用的 API（按产品系列和热门程度分组）。如果列表中没有显示您要启用的 API，请使用搜索功能查找该 API，或点击 API 所属的产品系列中的查看全部。
4. 选择您要启用的 API，然后点击启用按钮。
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

创建授权凭据

任何使用 OAuth 2.0 访问 Google API 的应用都必须拥有授权凭据，向 Google 的 OAuth 2.0 服务器证明应用的身份。以下步骤介绍了如何为您的项目创建凭据。然后，您的应用就可以使用这些凭据访问您为该项目启用的 API。

1. Go to the Credentials page.
2. 依次点击创建凭据 > OAuth 客户端 ID。
3. 以下部分介绍了 Google 授权服务器支持的客户端类型和重定向方法。选择为应用推荐的客户端类型，为您的 OAuth 客户端命名，然后适当设置表单中的其他字段。

确定访问权限范围

通过范围，您的应用可以仅请求访问所需的资源，同时还可以控制用户向您的应用授予的访问权限大小。因此，请求的范围数量与征得用户同意的可能性之间可能存在反向关系。

在开始实现 OAuth 2.0 授权之前，我们建议您确定您的应用需要访问权限的范围。

OAuth 2.0 API 范围文档包含可用于访问 Google API 的范围的完整列表。

获取 OAuth 2.0 访问令牌

以下步骤显示了您的应用如何与 Google 的 OAuth 2.0 服务器进行交互，以征得用户的同意，以代表用户执行 API 请求。您的应用必须先获得用户的同意，然后才能执行需要用户授权的 Google API 请求。

第 1 步：生成代码验证程序并进行验证

Google 支持适用于代码交换的证明密钥 (PKCE) 协议，以提高已安装的应用流程的安全性。系统会为每个授权请求创建一个唯一代码验证程序，并将其转换后的值“code_challenge”发送到授权服务器以获取授权代码。

创建代码验证程序

code_verifier 是高熵加密随机字符串，使用非保留字符 [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"，最少 43 个字符，最大 128 个字符。

代码验证程序应具有足够的熵，使得猜测值变得不切实际。

创建代码挑战

系统支持两种创建代码质询的方法。

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

第 2 步：向 Google 的 OAuth 2.0 服务器发送请求

要获取用户授权，请通过 https://accounts.google.com/o/oauth2/v2/auth 向 Google 的授权服务器发送请求。此端点会处理主动会话查找，对用户进行身份验证，并征得用户同意。端点只能通过 SSL 访问，并且会拒绝 HTTP（非 SSL）连接。

对于授权的应用，授权服务器支持以下查询字符串参数：

授权网址示例

以下标签页显示了不同重定向 URI 选项的示例授权网址。

除了 redirect_uri 参数的值外，这些网址完全相同。这些网址还包含所需的 response_type 和 client_id 参数以及可选的 state 参数。为便于阅读，每个网址都包含换行符和空格。

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

第 3 步：Google 提示用户同意

在此步骤中，用户决定是否向您的应用请求访问。在此阶段，Google 会显示一个同意窗口，其中会显示您的应用名称以及使用用户的授权凭据请求访问的 Google API 服务以及要授予的访问权限范围摘要。然后，用户可以同意向您应用请求的一个或多个范围授予访问权限，或拒绝该请求。

在此阶段，您的应用无需执行任何操作，因为它等待 Google 的 OAuth 2.0 服务器的响应，以表明是否已授予任何访问权限。下一步中会说明该响应。

第 4 步：处理 OAuth 2.0 服务器响应

应用收到授权响应的方式取决于其使用的重定向 URI 架构。无论采用哪种方案，响应都会包含授权代码 (code) 或错误 (error)。例如，error=access_denied 表示用户已拒绝请求。

如果用户向您的应用授予访问权限，您可以使用授权代码交换访问令牌和刷新令牌，如下一步中所述。

第 5 步：使用授权代码交换刷新令牌和访问令牌

如需用授权代码换取访问令牌，请调用 https://oauth2.googleapis.com/token 端点并设置以下参数：

以下代码段展示了一个示例请求：

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google 通过返回包含短期访问令牌和刷新令牌的 JSON 对象来响应此请求。

响应包含以下字段：

以下代码段显示了一个响应示例：

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

调用 Google API

在您的应用获得访问令牌后，您可以使用该令牌代表指定用户帐号调用 Google API（如果 API 所需的访问权限范围已被授予的话）。为此，请在向 API 发出的请求中添加访问令牌，具体方法是添加 access_token 查询参数或 Authorization HTTP 标头 Bearer 值。请尽可能使用 HTTP 标头，因为查询字符串通常会显示在服务器日志中。在大多数情况下，您可以使用客户端库来设置对 Google API 的调用（例如，在调用 Drive Files API 时）。

您可以访问 OAuth 2.0 Playground，试用所有 Google API 并查看其范围。

HTTP GET 示例

使用 Authorization: Bearer HTTP 标头调用 drive.files 端点 (Drive Files API) 的过程可能如下所示。请注意，您需要指定自己的访问令牌：

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

以下是使用 access_token 查询字符串参数对经过身份验证的用户的同一 API 的调用：

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl 示例

您可以使用 curl 命令行应用测试这些命令。下面是一个使用 HTTP 标头选项（首选）的示例：

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

或者，查询字符串参数选项：

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

刷新访问令牌

访问令牌会定期过期，并成为相关 API 请求的无效凭据。如果您请求访问与令牌关联的范围，则可以刷新访问令牌，而无需提示用户授予权限（包括当用户不在场时）。

如需刷新访问令牌，您的应用会向 Google 的授权服务器 (https://oauth2.googleapis.com/token) 发送 HTTPS POST 请求，其中包含以下参数：

以下代码段展示了一个示例请求：

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

只要用户尚未撤消授予应用的访问权限，令牌服务器就会返回一个包含新访问令牌的 JSON 对象。以下代码段是一个响应示例：

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

请注意，将颁发的刷新令牌数量有限；每个客户端/用户组合一个限制，所有客户端上的每个用户都不同。您应将刷新令牌保存在长期存储空间中，只要令牌仍然有效，就可以继续使用。如果您的应用请求刷新令牌的次数过多，则可能会遇到这些限制，在这种情况下，较旧的刷新令牌将停止工作。

撤消令牌

在某些情况下，用户可能希望撤消对应用的访问权限。用户可以通过访问 帐号设置来撤消访问权限。如需了解详情，请参阅有权访问您帐号的第三方网站和应用的“撤消网站或应用访问权限”部分。

应用也能够以编程方式撤消授予它的访问权限。用户退订、移除应用，或者应用所需的 API 资源发生了显著变化的情况，程序化撤消至关重要。换言之，移除流程的一部分可能包含 API 请求，以确保移除之前授予应用的权限。

为了以编程方式撤消令牌，您的应用会向 https://oauth2.googleapis.com/revoke 发出请求，并将令牌添加为参数：

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

该令牌可以是访问令牌，也可以是刷新令牌。如果此令牌是访问令牌，且具有相应的刷新令牌，则该令牌也会一并撤消。

如果已成功撤消调用，则响应的 HTTP 状态代码为 200。对于错误情况，系统会返回 HTTP 状态代码 400 以及错误代码。

延伸阅读

IETF 当前最佳做法适用于原生应用的 OAuth 2.0 制定了此处所述的许多最佳做法。