此页面由 Cloud Translation API 翻译。

适用于客户端 Web 应用的 OAuth 2.0

本文档介绍了如何实现 OAuth 2.0 授权，以便从 JavaScript Web 应用访问 Google API。OAuth 2.0 允许用户与应用共享特定数据，同时保持其用户名、密码和其他信息的私密性。例如，应用可以使用 OAuth 2.0 向用户授予在其 Google 云端硬盘中存储文件的权限。

此 OAuth 2.0 流程称为“隐式授权”流程。它专为仅在用户当前使用时访问 API 的应用而设计。这些应用无法存储机密信息。

在此流程中，您的应用会打开一个 Google 网址，该网址使用查询参数来识别您的应用以及该应用所需的 API 访问权限类型。您可以在当前浏览器窗口或弹出式窗口中打开该网址。用户可以通过 Google 进行身份验证并授予请求的权限。然后，Google 将用户重定向回您的应用。该重定向包含一个访问令牌，您的应用会验证该访问令牌，然后使用此令牌发出 API 请求。

Google API 客户端库和 Google Identity 服务

如果您使用适用于 JavaScript 的 Google API 客户端库向 Google 发出经过授权的调用，则应使用 Google Identity 服务 JavaScript 库来处理 OAuth 2.0 流程。请参阅 Google 身份服务的令牌模型，该模型基于 OAuth 2.0 隐式授权流程。

前提条件

为您的项目启用 API

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

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

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

创建授权凭据

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

Go to the Credentials page.
依次点击创建凭据 > OAuth 客户端 ID。
选择 Web 应用应用类型。
填写表单。使用 JavaScript 发出已获授权的 Google API 请求的应用必须指定经授权的 JavaScript 来源。该源标识您的应用可以从哪些网域向 OAuth 2.0 服务器发送请求。这些源站必须遵守 Google 的验证规则。

确定访问权限范围

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

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

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

获取 OAuth 2.0 访问令牌

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

第 1 步：重定向到 Google 的 OAuth 2.0 服务器

如需请求访问用户数据的权限，请将用户重定向到 Google 的 OAuth 2.0 服务器。

OAuth 2.0 端点

生成一个网址，以从 Google 的 OAuth 2.0 端点 (https://accounts.google.com/o/oauth2/v2/auth) 请求访问权限。此端点可通过 HTTPS 访问；普通 HTTP 连接会被拒绝。

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

参数

client_id

必需

您的应用的客户端 ID。您可以在 API Console Credentials page中找到此值。

redirect_uri

必需

确定 API 服务器在用户完成授权流程后将用户重定向到何处。该值必须与 OAuth 2.0 客户端的某个已获授权的重定向 URI 完全匹配，该 URI 与您在客户端的 API Console Credentials page中配置。如果此值与提供的 client_id 的授权重定向 URI 不匹配，您会收到 redirect_uri_mismatch 错误。

请注意，http 或 https 架构、大小写以及尾随斜杠 (/) 必须全部匹配。

response_type

必需

JavaScript 应用需要将该参数的值设置为 token。此值指示 Google 授权服务器以 name=value 对的形式，在完成授权流程后将用户重定向到的 URI (#) 的片段标识符中返回访问令牌。

scope

必需

以空格分隔的范围列表，用于标识您的应用可以代表用户访问的资源。这些值会告知 Google 向用户显示的权限请求页面。

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

我们建议您的应用尽可能在上下文中请求访问授权范围。通过在上下文中通过增量授权请求访问用户数据，您可以帮助用户更轻松地了解您的应用为何需要所请求的访问权限。

state

指向 Google 授权服务器的重定向示例

示例网址如下所示，使用了换行符和空格，以方便阅读。

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

创建请求网址后，将用户重定向到该网址。

JavaScript 示例代码

以下 JavaScript 代码段展示了如何在不使用 JavaScript 版 Google API 客户端库的情况下，通过 JavaScript 启动授权流程。由于此 OAuth 2.0 端点不支持跨域资源共享 (CORS)，因此该代码段会创建一个表单来打开向该端点的请求。

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

第 2 步：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_client`

发出请求的来源未获得此客户端的授权。请参阅 origin_mismatch。

`invalid_grant`

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

`origin_mismatch`

发起授权请求的 JavaScript 的架构、网域和/或端口可能与已为 OAuth 客户端 ID 注册的已获授权的 JavaScript 来源 URI 不一致。查看 Google API Console Credentials page中已获授权的 JavaScript 来源。

`redirect_uri_mismatch`

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

发起授权请求的 JavaScript 的架构、网域和/或端口可能与已为 OAuth 客户端 ID 注册的已获授权的 JavaScript 来源 URI 不一致。在 Google API Console Credentials page中查看已获授权的 JavaScript 来源。

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

`invalid_request`

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

此请求的格式不正确
请求缺少必需的参数
请求使用了 Google 不支持的授权方法。验证您的 OAuth 集成是否使用了推荐的集成方法

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

调用 Google API

完整示例

OAuth 2.0 端点

此代码示例演示了如何在不使用 JavaScript 版 Google API 客户端库的情况下，使用 JavaScript 完成 OAuth 2.0 流程。该代码适用于显示尝试 API 请求的按钮的 HTML 网页。如果您点击该按钮，代码就会检查页面是否已在浏览器的本地存储空间中存储 API 访问令牌。如果是，它会执行 API 请求。否则，它会启动 OAuth 2.0 流程。

对于 OAuth 2.0 流程，页面会执行以下步骤：

它会将用户定向到 Google 的 OAuth 2.0 服务器，该服务器会请求对 https://www.googleapis.com/auth/drive.metadata.readonly 范围的访问权限。
在授予（或拒绝）对一个或多个所请求范围的访问权限后，用户会被重定向到原始页面，原始页面会从片段标识符字符串中解析访问令牌。
该页面使用访问令牌发出示例 API 请求。

该 API 请求会调用 Drive API 的 about.get 方法，以检索有关已获授权用户的 Google 云端硬盘帐号的信息。
如果请求成功执行，则浏览器的调试控制台中会记录 API 响应。

您可以通过 Google 帐号的权限页面撤消对应用的访问权限。该应用将被列为 Google API 文档的 OAuth 2.0 演示。

如需在本地运行此代码，您需要为与您的授权凭据对应的 YOUR_CLIENT_ID 和 YOUR_REDIRECT_URI 变量设置值。YOUR_REDIRECT_URI 变量应设置为提供相应网页的同一网址。该值必须与您在 API Console Credentials page中配置的 OAuth 2.0 客户端的某个已授权重定向 URI 完全匹配。如果此值与已获授权的 URI 不匹配，您会收到 redirect_uri_mismatch 错误。您的项目还必须针对此请求启用适当的 API。

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0) {
    localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
    if (params['state'] && params['state'] == 'try_sample_request') {
      trySampleRequest();
    }
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null);
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
                  'state': 'try_sample_request',
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

JavaScript 源验证规则

为了帮助开发者确保应用的安全性，Google 会对 JavaScript 来源应用以下验证规则。您的 JavaScript 来源必须遵循这些规则。如需查看下文中网域、主机和架构的定义，请参阅 RFC 3986 第 3 节。

验证规则
架构	JavaScript 来源必须使用 HTTPS 架构，而不是普通的 HTTP。本地主机 URI（包括 localhost IP 地址 URI）不受此规则限制。
主机	主机不能是原始 IP 地址。本地主机 IP 地址不受此规则限制。
网域	主机 TLD（顶级域名）必须属于公共后缀列表。主域不能为 `“googleusercontent.com”`。 JavaScript 来源不能包含网址 Shortener 网域（例如 `goo.gl`），除非应用拥有该网域。
用户信息	JavaScript 来源不能包含 userinfo 子组件。
路径	JavaScript 来源不能包含路径组件。
查询	JavaScript 来源不能包含查询组件。
fragment	JavaScript 来源不能包含 fragment 组件。
字符	JavaScript 来源不能包含某些字符，包括：通配符 (`'*'`) 不可打印的 ASCII 字符百分号编码无效（任何不符合网址编码形式（百分号后两位十六进制数字）的网址编码格式 Null 字符（编码的 NULL 字符，例如，`%00`、`%C0%80`）

增量授权

在 OAuth 2.0 协议中，您的应用会请求对访问由范围标识的资源的授权。在需要资源时请求对资源进行授权被认为是最佳用户体验做法。为了实现这种做法，Google 的授权服务器支持增量授权。此功能允许您根据需要请求范围，如果用户授予新范围的权限，则会返回授权代码，您可以使用该代码来交换包含用户授予项目的所有范围的令牌。

例如，如果应用允许用户采样音乐曲目和创建混音，在登录时可能需要很少的资源，或许只需要登录用户的姓名即可。不过，保存已完成的合辑需要访问其 Google 云端硬盘。如果仅在应用确实需要时访问权限时请求他们访问 Google 云端硬盘，大多数人会发现很自然。

在这种情况下，应用在登录时可能会请求 openid 和 profile 范围以执行基本登录，然后在第一次请求时请求 https://www.googleapis.com/auth/drive.file 范围以保存组合。

以下规则适用于通过增量授权获得的访问令牌：

令牌可用于访问与滚动到新的合并授权的任何范围相对应的资源。
当您将刷新令牌用于合并授权以获取访问令牌时，访问令牌表示合并授权，可用于响应中包含的任何 scope 值。
组合授权包括用户向 API 项目授予的所有范围，即使授权是从不同的客户端请求也是如此。例如，如果用户使用应用的桌面客户端向同一应用授予了对一个范围的访问权限，然后通过移动客户端向同一应用授予了另一个范围，则组合授权将同时包括这两个范围。
如果您撤消代表合并授权的令牌，则代表关联用户对该授权的所有范围的访问权限也会同时撤消。

以下代码示例展示了如何向现有访问令牌添加范围。此方法可让您的应用避免管理多个访问令牌。

撤消令牌

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

应用也可以通过编程方式撤消已授予其的访问权限。当用户退订、移除应用或应用所需的 API 资源发生显著变化时，程序化撤消就非常重要。换言之，移除流程的一部分可以包含 API 请求，以确保移除之前授予应用的权限。

适用于客户端 Web 应用的 OAuth 2.0

Google API 客户端库和 Google Identity 服务

前提条件

为您的项目启用 API

创建授权凭据

确定访问权限范围

获取 OAuth 2.0 访问令牌

第 1 步：重定向到 Google 的 OAuth 2.0 服务器

OAuth 2.0 端点

指向 Google 授权服务器的重定向示例

JavaScript 示例代码

第 2 步：Google 提示用户同意

错误数

admin_policy_enforced

disallowed_useragent

Android

iOS

org_internal

invalid_client

invalid_grant

origin_mismatch

redirect_uri_mismatch

invalid_request

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

OAuth 2.0 端点

OAuth 2.0 服务器响应示例

调用 Google API

OAuth 2.0 端点

HTTP GET 示例

curl 示例

JavaScript 示例代码

完整示例

OAuth 2.0 端点

JavaScript 源验证规则

增量授权

OAuth 2.0 端点

撤消令牌

OAuth 2.0 端点

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_client`

`invalid_grant`

`origin_mismatch`

`redirect_uri_mismatch`

`invalid_request`

`curl` 示例