适用于移动应用和桌面应用的 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 流程:

前提条件

为您的项目启用 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 项目编辑器的“General”窗格或“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 Developer Account 文档中的查找您的团队 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 是一种深层链接,它使用自定义定义的架构来打开您的应用。

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

使用 Android 版 Google 登录 SDK,它可以直接向您的应用提供 OAuth 2.0 响应,从而无需重定向 URI。

如何迁移到 Android 版 Google 登录服务 SDK

如果您目前在 Android 上使用自定义架构进行 OAuth 集成,则需要完成以下步骤,以便完全迁移为使用推荐的 Android SDK Google 登录:

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

要迁移到 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。如需详细了解自定义 URI scheme 值的格式,请参阅 redirect_uri 参数定义。
    2. 记下配置 Google 登录 SDK 所需的 scopeclient_id 请求参数。
    3. 按照 开始将 Google 登录功能集成到您的 Android 应用中的说明设置 SDK。您可以跳过获取后端服务器的 OAuth 2.0 客户端 ID 步骤,因为您要重复使用在上一步中检索到的 client_id
    4. 按照 启用服务器端 API 访问权限说明进行操作。具体步骤如下:
      1. 使用 getServerAuthCode 方法检索您要请求权限的范围的授权代码。
      2. 将授权代码发送到应用的后端,以用它来换取访问令牌和刷新令牌。
      3. 使用检索到的访问令牌,代表用户调用 Google API。
  2. 在 Google API 控制台中停用对自定义 scheme 的支持:
    1. 前往 OAuth 2.0 凭据列表,然后选择您的 Android 客户端。
    2. 转到高级设置部分,取消选中启用自定义 URI scheme 复选框,然后点击 Save 以停用自定义 URI scheme 支持。
启用自定义 URI scheme
如果推荐的替代方案不适用于您,您可以按照以下说明为您的 Android 客户端启用自定义 URI scheme:
  1. 前往 OAuth 2.0 凭据列表,然后选择您的 Android 客户端。
  2. 转到高级设置部分,选中启用自定义 URI 架构复选框,然后点击保存以启用自定义 URI 架构支持。
在 Chrome 应用中使用自定义 URI scheme 的替代方案

使用 Chrome Identity API,该 API 可直接向您的应用提供 OAuth 2.0 响应,从而无需重定向 URI。

验证应用所有权(Android、Chrome)

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

Android

要完成验证流程,您可以使用 Google Play 开发者帐号(如果有),并且您的应用已在 Google Play 管理中心注册。要成功完成验证,必须满足以下要求:

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

在 Android 客户端的验证应用所有权部分,点击验证所有权按钮以完成验证流程。

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

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

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

为完成验证流程,请使用您的 Chrome 应用商店开发者帐号。 为确保验证成功,必须满足以下要求:

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

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

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

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

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

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

环回 IP 地址(macOS、Linux、Windows 桌面设备)

如需使用此网址接收授权代码,您的应用必须监听本地网络服务器。这种做法适用于许多平台,但还不是所有平台。但是,如果您的平台支持,则建议您使用此机制来获取授权代码。

当您的应用收到授权响应时,为了最大程度地提高可用性,它应显示一个 HTML 页面来指示用户关闭浏览器并返回您的应用。

推荐用法 macOS、Linux 和 Windows 桌面(但不是通用 Windows 平台)应用
表单值 将应用类型设置为桌面应用

手动复制/粘贴

确定访问权限范围

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

在开始实现 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 的授权服务器如何向您的应用发送响应。系统提供多种重定向选项,以供已安装的应用使用,并且您在设置授权凭据时也考虑了特定的重定向方法。

该值必须与您在客户端的 API Console Credentials page中配置的 OAuth 2.0 客户端的某个已授权重定向 URI 完全匹配。如果此值与已获授权的 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 网址不同。
环回 IP 地址 http://127.0.0.1:porthttp://[::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。此参数仅支持 S256plain 值。

state 建议

指定您的应用用来维护授权请求和授权服务器响应之间的状态的任何字符串值。当用户同意或拒绝应用的访问请求后,服务器会返回您在 redirect_uri 的网址片段标识符 (#) 中以 name=value 对形式发送的确切值。

您可以将此参数用于多种用途,例如将用户定向到应用中的正确资源、发送 Nonce,以及减少跨站请求伪造问题。由于您的 redirect_uri 可以被猜到,因此使用 state 值可以提高您的传入连接是身份验证请求结果的可能性。如果您生成随机字符串,或对 Cookie 或其他用于捕获客户端状态的值的哈希值进行编码,则可以验证响应,以额外确保请求和响应均来自同一浏览器,从而防范跨站请求伪造等攻击。如需查看如何创建和确认 state 令牌的示例,请参阅 OpenID Connect 文档。

login_hint 可选

如果您的应用知道哪个用户正在尝试进行身份验证,它可以使用此参数向 Google Authentication 服务器提供提示。服务器会根据该提示,通过在登录表单中预填充电子邮件字段或选择适当的多登录会话来简化登录流程。

将该参数值设为电子邮件地址或 sub 标识符,该标识符相当于用户的 Google ID。

授权网址示例

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

除了 redirect_uri 参数的值之外,这些网址完全相同。这些网址还包含必需的 response_typeclient_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 应用在嵌入式用户代理中打开常规网页链接,并且用户从您的网站转到 Google 的 OAuth 2.0 授权端点时,Web 开发者可能会遇到此错误。开发者应允许在操作系统的默认链接处理程序(包括 Android App Links 处理程序或默认浏览器应用)中打开常规链接。Android 自定义标签页库也是一个受支持的选项。

iOS

iOS 和 macOS 开发者在 WKWebView 中打开授权请求时可能会遇到此错误。 开发者应改用 iOS 库,例如 Google 登录适用于 iOS 或 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 使用自定义 URI 架构:如果您看到 Chrome 应用不支持自定义 URI schemeAndroid 客户端未启用自定义 URI scheme,则表示您使用的是 Chrome 应用不支持的自定义 URI 架构,该机制在 Android 上默认处于停用状态。详细了解自定义 URI scheme 替代方案

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

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

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

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

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

字段
client_id Credentials page中获取的客户端 ID。 API Console
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 注意:只有在您的请求包含身份范围(例如 openidprofileemail)时,系统才会返回此属性。该值是一个 JSON Web 令牌 (JWT),其中包含有关用户的经过数字签名的身份信息。
refresh_token 可用于获取新访问令牌的令牌。刷新令牌在用户撤消访问权限之前一直有效。请注意,系统始终会为已安装的应用返回刷新令牌。
scope access_token 授予的访问权限范围,表示为以空格分隔、区分大小写的字符串列表。
token_type 返回的令牌的类型。此时,此字段的值始终设置为 Bearer

以下代码段展示了一个示例响应:

{
  "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。为此,请通过加入 access_token 查询参数或 Authorization HTTP 标头 Bearer 值,将访问令牌添加到对 API 的请求中。请尽可能使用 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 请求,其中包含以下参数:

字段
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 确立了此处介绍的许多最佳做法。