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

本概览总结了 Google 支持的 OAuth 2.0 流程，这些流程可帮助您确保为应用选择了正确的流程。

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

OAuth 2.0 可让用户与应用共享特定数据，同时保持其用户名、密码和其他信息的私密性。例如，应用可以使用 OAuth 2.0 向用户授予在其 Google 云端硬盘中存储文件的权限。

安装式应用会分发给各个设备，系统会假定这些应用无法保密。当用户位于应用中或应用在后台运行时，他们可以访问 Google API。

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

替代方案

对于移动应用，您可能更倾向于使用适用于 Android 或 iOS 的 Google 登录功能。Google 登录客户端库可以处理身份验证和用户授权，而且这些库的实现可能比此处介绍的较低级别的协议更简单。

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

库和示例

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

• AppAuth for Android 库
• AppAuth for iOS 库
• 适用于应用的 OAuth：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，或点击其所属产品系列中的查看全部。
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 客户端命名，并根据情况设置表单中的其他字段。

Android

1. 选择 Android 应用类型。
2. 输入 OAuth 客户端的名称。此名称会显示在项目的 Credentials page 上，用于识别客户端。
3. 输入您的 Android 应用的软件包名称。此值在应用清单文件中 <manifest> 元素的 package 属性定义。
4. 输入应用分发的 SHA-1 签名证书指纹。
   • 如果您的应用使用 Google Play 应用签名，请从 Play 管理中心的“应用签名”页面复制 SHA-1 指纹。
   • 如果您自行管理密钥库和签名密钥，请使用 Java 附带的 keytool 实用程序以人类可读的格式输出证书信息。复制 keytool 输出的 Certificate fingerprints 部分中的 SHA1 值。如需了解详情，请参阅 Android 版 Google API 文档中的对客户端进行身份验证。
5. （可选）验证您对 Android 应用的所有权。
6. 点击创建。

iOS

1. 选择 iOS 应用类型。
2. 输入 OAuth 客户端的名称。此名称会显示在项目的 Credentials page 上，用于识别客户端。
3. 输入应用的软件包标识符。软件包 ID 是应用的信息属性列表资源文件 (info.plist) 中 CFBundleIdentifier 键的值。该值最常显示在“常规”窗格或 Xcode 项目编辑器的“Signing & Capabilities”（签名和功能）窗格中。软件包 ID 也会显示在 Apple 的 App Store Connect 网站上相应应用的“应用信息”页面的“常规信息”部分中。
4. （可选）

   如果应用已在 Apple 的 App Store 中发布，请输入应用的 App Store ID。商店 ID 是每个 Apple App Store 网址中包含的数字字符串。

   1. 在 iOS 或 iPadOS 设备上打开 Apple App Store 应用。
   2. 搜索您的应用。
   3. 选择“分享”按钮（方形和向上箭头符号）。
   4. 选择复制链接。
   5. 将链接粘贴到文本编辑器中。App Store ID 是网址的最后一部分。

      示例：https://apps.apple.com/app/google/id284815942

5. （可选）

   输入您的团队 ID。如需了解详情，请参阅 Apple 开发者帐号文档中的查找团队 ID。

6. 点击创建。

UWP

1. 选择通用 Windows 平台应用类型。
2. 输入 OAuth 客户端的名称。此名称会显示在项目的 Credentials page 上，用于识别客户端。
3. 输入应用的 Microsoft Store ID（12 个字符）。您可以在 Microsoft 合作伙伴中心内“应用管理”部分的应用身份页面上找到此值。
4. 点击创建。

对于 UWP 应用，自定义 URI scheme 不得超过 39 个字符。

自定义 URI scheme（Android、iOS、UWP）

自定义 URI scheme 是一种深层链接，它使用自定义的 scheme 来打开您的应用。

重要提示：新的 Chrome 应用不再支持自定义 URI scheme。由于存在应用冒充行为的风险，自定义 URI scheme 在新的 Android 客户端上默认处于停用状态。

在 Android 上使用自定义 URI scheme 的替代方案

使用 Android 版 Google 登录 SDK，该 SDK 可将 OAuth 2.0 响应直接传送至您的应用，这样您便无需重定向 URI。

如何迁移到 Android 版 Google 登录 SDK

如果您目前在 Android 上为 OAuth 集成使用自定义方案，则需要完成以下步骤，才能完全迁移到推荐的 Android 版 Google 登录 SDK：

1. 更新您的代码，以使用 Google 登录 SDK。
2. 在 Google API 控制台中停用对自定义架构的支持。

注意：在 Google API 控制台中停用对自定义架构的支持之前，您应该完成和部署代码更新（考虑用户群或旧款设备的采用时间），以免用户在尝试使用您的应用时收到 invalid_request 错误消息。

如需迁移到 Google 登录 Android SDK，请按以下步骤操作：

1. 更新您的代码，以使用 Google 登录 Android SDK：
   1. 检查您的代码，确定您在哪里向 Google 的 OAuth 2.0 服务器发送请求；如果您使用的是自定义架构，那么您的请求将如下所示：

        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        

      com.example.app:/oauth2redirect 是上述示例中的自定义架构重定向 URI。请参阅 redirect_uri 参数定义，详细了解自定义 URI 架构值的格式。
   2. 记下配置 Google 登录 SDK 所需的 scope 和 client_id 请求参数。
      注意：如果您使用的是第三方库，请查看该库的配置文件以找到这些信息。
   3. 请按照 开始将 Google 登录功能集成到您的 Android 应用中的说明设置 SDK。您可以跳过获取后端服务器的 OAuth 2.0 客户端 ID 步骤，就像重复使用上一步中检索到的 client_id 一样。
   4. 按照 启用服务器端 API 访问权限说明进行操作。包括以下步骤：
      1. 使用 getServerAuthCode 方法检索您要请求权限的范围的授权代码。
      2. 将授权代码发送到应用的后端，以用其换取访问和刷新令牌。
      3. 使用检索到的访问令牌代表用户调用 Google API。
      注意：如果您的应用不需要离线访问，请改为按照 这些说明请求客户端 API 访问权限。
2. 在 Google API 控制台中停用对自定义架构的支持：
   1. 前往您的 OAuth 2.0 凭据列表，然后选择您的 Android 客户端。
   2. 转到高级设置部分，取消选中启用自定义 URI 协议复选框，然后点击保存以停用自定义 URI 方案支持。

启用自定义 URI scheme

如果推荐的替代方法对您不适用，您可以按照以下说明为您的 Android 客户端启用自定义 URI scheme：

1. 前往 OAuth 2.0 凭据列表，然后选择您的 Android 客户端。
2. 转到高级设置部分，选中启用自定义 URI 协议复选框，然后点击保存以启用自定义 URI 架构支持。

在 Chrome 应用中使用自定义 URI scheme 的替代方法

使用 Chrome Identity API，将 OAuth 2.0 响应直接传送至您的应用，无需重定向 URI。

验证应用所有权（Android、Chrome）

您可以验证应用的所有权，以降低应用被假冒的风险。

Android

注意：Android 应用所有权验证目前仅适用于 Google Play 应用。

为完成验证流程，您可以使用自己的 Google Play 开发者帐号（如果有），并且已在 Google Play 管理中心注册您的应用。若要成功验证，必须满足以下要求：

• 您必须在 Google Play 管理中心内有一个已注册的应用，该应用的软件包名称和 SHA-1 签名证书指纹必须与您要完成验证的 Android OAuth 客户端具有相同的软件包名称和 SHA-1 签名证书指纹。
• 您必须在 Google Play 管理中心内拥有应用的管理员权限。 详细了解 Google Play 管理中心内的访问权限管理。

在 Android 客户端的 Verify App Ownership 部分中，点击 Verify Ownership 按钮以完成验证流程。

如果验证成功，系统会显示一条通知，确认验证流程已成功。否则，系统会显示错误提示。

要解决验证失败的问题，请尝试以下操作：

• 请确保您要验证的应用是 Google Play 管理中心内的注册应用。
• 确保您在 Google Play 管理中心内拥有该应用的管理员权限。

Chrome

要完成验证流程，您需要使用自己的 Chrome 应用商店开发者帐号。 若要成功验证，必须满足以下要求：

• 您必须在 Chrome 应用商店开发者信息中心内注册一个商品，并且该商品的 ID 必须与您要完成验证的 Chrome 扩展程序 OAuth 客户端的 ID 相同。
• 您必须是 Chrome 应用商店商品的发布商。详细了解 Chrome 应用商店开发者信息中心内的访问权限管理。

在 Chrome 扩展程序客户端的验证应用所有权部分，点击验证所有权按钮以完成验证流程。

注意：向您的帐号授予访问权限后，请等待几分钟，然后再完成验证流程。

如果验证成功，系统会显示一条通知，确认验证流程已成功。否则，系统会显示错误提示。

要解决验证失败的问题，请尝试以下操作：

• 确保 Chrome 应用商店开发者信息中心内有一项注册的内容，且该内容的 ID 与您要完成验证的 Chrome 扩展程序 OAuth 客户端的内容 ID 相同。
• 确保您是应用的发布者，即，您必须是应用的个人发布者或应用群组发布者的成员。详细了解 Chrome 应用商店开发者信息中心内的访问权限管理。
• 如果您刚刚更新了群组发布者列表，请在 Chrome 应用商店开发者信息中心内验证群组发布者成员资格列表是否已同步。 详细了解如何同步您的发布商成员资格列表。

环回 IP 地址（macOS、Linux、Windows 桌面设备）

重要提示：对于 Android、Chrome 应用和 iOS OAuth 客户端类型，环回 IP 地址重定向选项已弃用。请参阅环回 IP 地址迁移指南，了解如何迁移到受支持的替代方案。

若要使用此网址接收授权代码，您的应用必须监听本地网络服务器。这种做法适用于许多（但不是所有）平台。不过，如果您的平台支持，建议您使用该方式获取授权代码。

当您的应用收到授权响应时，为了获得最佳可用性，应用应显示一个 HTML 页面来指示用户关闭浏览器并返回您的应用以做出响应。

推荐用法	macOS、Linux 和 Windows 桌面设备（但不是通用 Windows 平台）应用
表单值	将应用类型设为桌面应用。

注意：如需详细了解环回 IP 地址，请参阅 redirect_uri 参数定义。您也可以使用 localhost 代替环回 IP，但此配置可能会导致客户端防火墙出现问题。大多数（但并非所有）防火墙都允许环回通信。

手动复制/粘贴

重要提示： 不再支持手动复制/粘贴选项（也称为带外 (OOB) 重定向方法）。请参阅 OOB 迁移指南，了解如何迁移到安全的替代方案。

确定访问权限范围

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

在开始实现 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 个字符。

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

创建代码质询

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

代码验证生成方法
S256（推荐）	代码质询是代码验证程序的 Base64网址（无填充）编码的 SHA256 哈希。 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
普通	代码质询与上面生成的代码验证程序的值相同。 code_challenge = code_verifier

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

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

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

参数
client_id	必需 您的应用的客户端 ID。您可以在 API Console Credentials page中找到此值。
redirect_uri	必需 确定 Google 的授权服务器如何向您的应用发送响应。有多个适用于已安装的应用的重定向选项，您在设置授权凭据时考虑了特定的重定向方法。 该值必须与 OAuth 2.0 客户端的某个已获授权的重定向 URI 完全匹配，该 URI 已在客户端的 API Console Credentials page中配置。如果此值与已获授权的 URI 不匹配，您会收到 redirect_uri_mismatch 错误。 下表显示了每种方法的相应 redirect_uri 参数值： redirect_uri 值 自定义 URI scheme com.example.app:redirect_uri_path 或 com.googleusercontent.apps.123:redirect_uri_path com.example.app 是您控制的域名的反向 DNS 表示法。自定义架构必须包含英文句点才有效。 com.googleusercontent.apps.123 是客户端 ID 的反向 DNS 表示法。 redirect_uri_path 是可选的路径组件，例如 /oauth2redirect。请注意，路径应该以一个斜杠开头，这不同于常规 HTTP 网址。 注意：Chrome 应用不再支持自定义 URI scheme，它们在 Android 上默认处于停用状态。 详细了解适用于 Android 和 Chrome 应用的自定义架构替代方案。 环回 IP 地址 http://127.0.0.1:port 或 http://[::1]:port 向您的平台查询相关环回 IP 地址，并在一个随机的可用端口上启动 HTTP 监听器。将 port 替换为您的应用监听的实际端口号。 请注意，移动应用 已弃用对环回 IP 地址重定向选项的支持。
response_type	必需 确定 Google OAuth 2.0 端点是否返回授权代码。 对于已安装的应用，请将参数值设为 code。
scope	必需 以空格分隔的范围列表，用于标识您的应用可以代表用户访问的资源。这些值会告知 Google 向用户显示的权限请求页面。 范围可让您的应用仅请求访问所需资源，同时还允许用户控制他们向您的应用授予的访问权限大小。因此，请求的范围数量与征得用户同意的可能性之间存在反向关系。
code_challenge	推荐 指定经过编码的 code_verifier，以便在授权代码交换期间用作服务器端质询。如需了解详情，请参阅上文的创建代码质询部分。
code_challenge_method	推荐 指定使用哪种方法对将在授权代码交换期间使用的 code_verifier 进行编码。此参数必须与上述 code_challenge 参数一起使用。如果 code_challenge_method 的值不存在于包含 code_challenge 的请求中，则其值默认为 plain。此参数仅支持 S256 或 plain 值。
state	推荐 指定您的应用用于维护授权请求和授权服务器响应之间的状态的任何字符串值。用户同意或拒绝您应用的访问请求后，服务器将在 redirect_uri 的网址片段标识符 (#) 中以 name=value 对形式返回您发送的确切值。 您可以将此参数用于多种用途，例如将用户定向到应用中的正确资源、发送 Nonce，以及减少跨网站请求伪造问题。由于您的 redirect_uri 可能会被猜到，因此使用 state 值可提高您确保传入连接是身份验证请求结果的几率。如果您生成随机字符串，或者对 Cookie 的哈希值或捕获客户端状态的其他值进行编码，则可以验证响应，以进一步确保请求和响应来自同一浏览器，从而防范跨网站请求伪造等攻击。如需查看有关如何创建和确认 state 令牌的示例，请参阅 OpenID Connect 文档。
login_hint	可选 如果您的应用知道哪个用户正在尝试进行身份验证，它可以使用此参数向 Google 身份验证服务器提供提示。服务器会使用该提示来简化登录流程，具体方法是：在登录表单中预填充电子邮件字段，或选择适当的多登录会话。 请将此参数值设为电子邮件地址或 sub 标识符，这相当于用户的 Google ID。

注意：由于客户端无法对 client_secret 进行保密，因此系统不支持对安装式应用进行增量授权。

授权网址示例

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

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

自定义 URI 协议

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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

环回 IP 地址

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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 服务器做出指示是否已授予任何访问权限的响应。以下步骤介绍了该响应。

错误数

向 Google 的 OAuth 2.0 授权端点发出的请求可能会显示面向用户的错误消息，而不是预期的身份验证和授权流程。下面列出了常见的错误代码和建议的解决方案。

admin_policy_enforced

根据 Google Workspace 管理员的政策，该 Google 帐号无法对所请求的一个或多个范围进行授权。请参阅 Google Workspace 管理员帮助文章： 控制哪些第三方应用和内部应用可以访问 Google Workspace 数据，详细了解管理员如何限制对您的所有范围或敏感范围和受限范围的访问权限，直到系统明确向您的 OAuth 客户端 ID 授予访问权限为止。

disallowed_useragent

授权端点显示在 Google 的 OAuth 2.0 政策所禁止的嵌入式用户代理中。

Android

Android 开发者在 android.webkit.WebView 中打开授权请求时可能会遇到此错误消息。 开发者应改用 Android 库，例如 Google 登录 Android 或 OpenID Foundation 的 AppAuth for Android。

当某个 Android 应用在嵌入式用户代理中打开常规 Web 链接，且用户从您的网站转到 Google 的 OAuth 2.0 授权端点时，Web 开发者可能会遇到此错误。开发者应允许在操作系统的默认链接处理程序（包括 Android App Links 处理程序或默认浏览器应用）中打开常规链接。Android 自定义标签页库也是一个受支持的选项。

iOS

iOS 和 macOS 开发者在 WKWebView 中打开授权请求时可能会遇到此错误。开发者应改用 iOS 库，例如 iOS 版 Google 登录或 OpenID Foundation 的 AppAuth for iOS。

当 iOS 或 macOS 应用在嵌入式用户代理中打开常规 Web 链接，且用户从您的网站转到 Google 的 OAuth 2.0 授权端点时，Web 开发者可能会遇到此错误。开发者应允许在操作系统的默认链接处理程序中打开常规链接，该处理程序包含通用链接处理程序或默认浏览器应用，也支持使用 SFSafariViewController 库。

org_internal

请求中的 OAuth 客户端 ID 属于项目的一部分，用于限制对特定 Google Cloud 组织中的 Google 帐号的访问权限。如需详细了解此配置选项，请参阅“设置 OAuth 同意屏幕”帮助文章中的用户类型部分。

invalid_grant

如果您使用的是代码验证程序和质询，则 code_callenge 参数无效或缺失。确保正确设置 code_challenge 参数。

刷新访问令牌时，令牌可能已过期或已失效。再次验证用户身份，并请求用户同意以获取新令牌。如果您仍然看到此错误，请确保您的应用已正确配置，并且您在请求中使用的令牌和参数正确无误。否则，用户帐号可能已被删除或停用。

redirect_uri_mismatch

授权请求中传递的 redirect_uri 与 OAuth 客户端 ID 的授权重定向 URI 不匹配。查看 Google API Console Credentials page中已获授权的重定向 URI。

传递的 redirect_uri 对于客户端类型可能无效。

redirect_uri 参数可能是指已弃用且不再受支持的 OAuth 带外 (OOB) 流程。请参阅迁移指南，更新您的集成。

invalid_request

您提出的请求出了点问题。这可能是由多种原因造成的：

• 此请求的格式不正确
• 请求缺少必需的参数
• 请求使用了 Google 不支持的授权方法。验证您的 OAuth 集成是否使用了推荐的集成方法
• 重定向 URI 使用了自定义架构：如果您看到错误消息“Chrome 应用不支持自定义 URI 架构”或“您的 Android 客户端未启用自定义 URI 架构”，则表示您使用的是 Chrome 应用不支持的自定义 URI 架构，该架构在 Android 上默认处于停用状态。详细了解自定义 URI scheme 替代方案

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

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

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

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

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

字段
client_id	从 API Console Credentials page中获取的客户端 ID。
client_secret	从 Credentials page API Console获得的客户端密钥。
code	初始请求返回的授权代码。
code_verifier	您在第 1 步中创建的代码验证程序。
grant_type	根据 OAuth 2.0 规范的定义，此字段的值必须设置为 authorization_code。
redirect_uri	在给定 client_id 的 API Console Credentials page 中为您的项目列出的某个重定向 URI。

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

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	您的应用发送的令牌，用于向 Google API 请求授权。
expires_in	访问令牌的剩余生命周期（以秒为单位）。
id_token	注意：只有当您的请求包含身份范围（例如 openid、profile 或 email）时，系统才会返回此属性。该值是一个 JSON Web 令牌 (JWT)，其中包含有关用户的数字签名身份信息。
refresh_token	可用于获取新访问令牌的令牌。刷新令牌在用户撤消访问权限之前一直有效。 请注意，系统始终会为已安装的应用返回刷新令牌。
scope	access_token 授予的访问权限范围，表示为以空格分隔且区分大小写的字符串列表。
token_type	返回的令牌类型。目前，此字段的值始终设置为 Bearer。

重要提示：您的应用应将两个令牌存储在一个安全、长期有效的位置，该位置可在不同的应用调用之间访问。当您的访问令牌到期时，刷新令牌可让您的应用获取新的访问令牌。因此，如果您的应用丢失了刷新令牌，用户将需要重复 OAuth 2.0 同意流程，以便您的应用能够获取新的刷新令牌。

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

{
  "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

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

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 请求，其中包含以下参数：

字段
client_id	从 API Console获得的客户端 ID。
client_secret	从 API Console获得的客户端密钥。（client_secret 不适用于注册为 Android、iOS 或 Chrome 应用的客户端的请求。）
grant_type	根据 OAuth 2.0 规范中的定义，此字段的值必须设置为 refresh_token。
refresh_token	通过授权代码交换返回的刷新令牌。

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

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 确立了本文所述的许多最佳实践。