本文档介绍了如何实现 OAuth 2.0 授权以从 JavaScript Web 应用访问 Google API。OAuth 2.0 可让用户与应用共享特定数据，同时保持其用户名、密码和其他信息的私密性。例如，应用可以使用 OAuth 2.0 向用户授予权限，以便将文件存储在他们的 Google 云端硬盘中。
此 OAuth 2.0 流程称为隐式授权流程。它专门针对那些仅在用户访问应用时才会访问 API 的应用。这些应用无法存储机密信息。
在此流程中，您的应用会打开一个 Google 网址，该网址使用查询参数来标识您的应用以及应用所需的 API 访问权限类型。您可以在当前浏览器窗口或弹出式窗口中打开该网址。用户可以向 Google 进行身份验证并授予所请求的权限。 然后，Google 会将用户重定向回您的应用。重定向包括一个访问令牌，您的应用会验证该令牌，然后使用它发出 API 请求。
前提条件
为您的项目启用 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 所属产品系列中的查看全部。
- 选择您要启用的 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 Scopes 文档包含可用于访问 Google API 的完整范围列表。
获取 OAuth 2.0 访问令牌
以下步骤显示了您的应用如何与 Google 的 OAuth 2.0 服务器进行交互，以获取用户同意执行 API 请求。您的应用必须获得上述同意后，才能执行需要用户授权的 Google API 请求。
第 1 步：配置客户端对象
如果您使用适用于 JavaScript 的 Google API 客户端库处理 OAuth 2.0 流程，则首先要配置 gapi.auth2 和 gapi.client 对象。这些对象使您的应用能够获取用户授权并发出已授权的 API 请求。
客户端对象用于标识应用请求访问权限的范围。这些值会告知用户 Google 向用户显示的同意屏幕。
JS 客户端库
JavaScript 客户端库简化了授权过程的许多方面：
- 它会为 Google 的授权服务器创建重定向网址，并提供一种将用户定向到该网址的方法。
- 它会处理从该服务器到您应用的重定向。
- 它会验证授权服务器返回的访问令牌。
- 它存储授权服务器发送至您的应用的访问令牌，并在您的应用随后进行已授权的 API 调用时检索该令牌。
以下代码段选自本文档后面显示的完整示例。此代码会初始化 gapi.client 对象，您的应用稍后将使用该对象进行 API 调用。创建该对象后，初始化该对象（用于检查和监控用户的授权状态）的 gapi.auth2 对象也会初始化。
调用 gapi.client.init 可指定以下字段：
apiKey和clientId值用于指定应用的授权凭据。如创建授权凭据部分所述，您可以在 API Console中获取这些值。请注意，如果您的应用发出已获授权的 API 请求，则需要clientId。仅发出未经授权的请求的应用只能指定 API 密钥。-
scope字段指定一系列以空格分隔的访问权限范围，这些范围对应于您的应用可代表用户访问的资源。这些值会通知 Google 向用户显示的同意屏幕。我们建议您的应用尽可能在上下文中请求对授权范围的访问权限。通过在情境中请求访问权限，用户可通过增量授权更轻松地理解您的应用为何需要所请求的访问权限。
discoveryDocs字段列出了您的应用使用的 API 发现文档。Discovery 文档介绍了 API 的表面（包括其资源架构），JavaScript 客户端库会使用这些信息生成应用可以使用的方法。 在此示例中，代码会检索版本 3 的 Google Drive API 的发现文档。
gapi.client.init 调用完成后，代码将设置 GoogleAuth 变量以标识 Google Auth 对象。最后，代码将设置一个在用户登录状态更改时调用函数的监听器。（代码段中未定义该函数。）
var GoogleAuth; // Google Auth object.
function initClient() {
gapi.client.init({
'apiKey': 'YOUR_API_KEY',
'clientId': 'YOUR_CLIENT_ID',
'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
'discoveryDocs': ['https://www.googleapis.com/discovery/v1/apis/drive/v3/rest']
}).then(function () {
GoogleAuth = gapi.auth2.getAuthInstance();
// Listen for sign-in state changes.
GoogleAuth.isSignedIn.listen(updateSigninStatus);
});
}
OAuth 2.0 端点
如果您要直接访问 OAuth 2.0 端点，可以继续执行下一步。
第 2 步：重定向到 Google 的 OAuth 2.0 服务器
如需请求访问用户的数据的权限，请将用户重定向到 Google 的 OAuth 2.0 服务器。
JS 客户端库
调用 GoogleAuth.signIn() 方法，将用户定向到 Google 的授权服务器。
GoogleAuth.signIn();
实际上，您的应用可能会设置布尔值，以确定在尝试调用 API 之前是否调用 signIn() 方法。
以下代码段展示了如何发起用户授权流程。请注意关于该代码段的以下几点：
-
代码中引用的
GoogleAuth对象与第 1 步中的代码段中定义的全局变量相同。 updateSigninStatus函数是一个监听器，可监听用户授权状态的更改。它在监听器中的角色也已在第 1 步的代码段中定义：GoogleAuth.isSignedIn.listen(updateSigninStatus);
代码段定义了另外两个全局变量：
isAuthorized是一个布尔值变量，用于指示用户是否已登录。该值可以在应用加载时进行设置，并在用户登录或退出应用时进行更新。在此代码段中，
sendAuthorizedApiRequest函数会检查变量的值，以确定应用是否应尝试需要授权的 API 请求，或提示用户授权应用。currentApiRequest是一个对象，用于存储用户尝试的最后一个 API 请求的详细信息。在应用调用sendAuthorizedApiRequest函数时，将设置对象的值。如果用户已授权应用，请求会立即执行。否则，该函数会将用户重定向。在用户登录后，
updateSignInStatus函数会调用sendAuthorizedApiRequest，并传入在授权流程开始之前尝试的同一个请求。
var isAuthorized;
var currentApiRequest;
/**
* Store the request details. Then check to determine whether the user
* has authorized the application.
* - If the user has granted access, make the API request.
* - If the user has not granted access, initiate the sign-in flow.
*/
function sendAuthorizedApiRequest(requestDetails) {
currentApiRequest = requestDetails;
if (isAuthorized) {
// Make API request
// gapi.client.request(requestDetails)
// Reset currentApiRequest variable.
currentApiRequest = {};
} else {
GoogleAuth.signIn();
}
}
/**
* Listener called when user completes auth flow. If the currentApiRequest
* variable is set, then the user was prompted to authorize the application
* before the request executed. In that case, proceed with that API request.
*/
function updateSigninStatus(isSignedIn) {
if (isSignedIn) {
isAuthorized = true;
if (currentApiRequest) {
sendAuthorizedApiRequest(currentApiRequest);
}
} else {
isAuthorized = false;
}
}
OAuth 2.0 端点
生成一个网址，以向 Google 的 OAuth 2.0 端点 (https://accounts.google.com/o/oauth2/v2/auth) 请求访问权限。此端点可通过 HTTPS 访问；普通 HTTP 连接会被拒绝。
对于网络服务器应用，Google 授权服务器支持下列查询字符串参数：
| 参数 | |||||||
|---|---|---|---|---|---|---|---|
client_id |
必需
您的应用的客户端 ID。您可以在 API ConsoleCredentials page中找到此值。 |
||||||
redirect_uri |
必需
确定用户完成授权流程后，API 服务器将用户重定向到的哪个位置。该值必须与您在客户端的 API ConsoleCredentials page中配置的 OAuth 2.0 客户端的某个已获授权的重定向 URI 完全一致。如果此值与所提供的 请注意， |
||||||
response_type |
必需
JavaScript 应用需要将参数值设置为 |
||||||
scope |
必需
用空格分隔的范围列表，用于标识您的应用可以代表用户访问的资源。这些值会告知用户 Google 向用户显示的同意屏幕。 通过范围，您的应用可以仅请求访问所需的资源，同时还能控制用户向您的应用授予的访问权限。因此，请求的范围数量与征得用户同意的可能性之间是相反的。 我们建议您的应用尽可能在上下文中请求访问授权范围。通过增量授权在上下文中请求访问用户数据，有助于用户更轻松地了解应用需要其请求的访问权限的原因。 |
||||||
state |
推荐
指定应用用于维护授权请求和授权服务器响应之间的状态的任何字符串值。在用户同意或拒绝您的应用的访问请求之后，服务器会返回您在 此参数可用于多种用途，例如将用户定向至应用中的正确资源、发送 Nonce 以及减少跨网站请求伪造。由于您的 |
||||||
include_granted_scopes |
可选参数
允许应用使用增量授权在上下文中请求访问其他范围。如果您将此参数的值设为 |
||||||
login_hint |
可选参数
如果您的应用知道哪个用户在尝试进行身份验证，它可以使用此参数向 Google 身份验证服务器提供提示。服务器会使用该提示简化登录流程，方法为：在登录表单中预先填写电子邮件字段，或选择相应的多帐号登录会话。 将参数值设为电子邮件地址或 |
||||||
prompt |
可选参数
以空格分隔的一系列提示，用于提示用户。如果您未指定此参数，则系统只会在用户首次请求访问项目时提示用户。如需了解详情，请参阅提示重新同意。 可能的值包括：
|
||||||
重定向至 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();
}
第 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.webkit.WebView 中打开授权请求时，Android 开发者可能会遇到此错误消息。开发者应改用 Android 库，例如 Android 版 Google 登录或 OpenID Foundation' 的 AppAuth for Android。
Android 应用会在嵌入式用户代理中打开常规网页链接，并且用户从您的网站导航到 Google 的 OAuth 2.0 授权端点时，可能会遇到此错误。开发者应允许打开操作系统的默认链接处理程序中的常规链接，其中包括 Android 应用链接处理程序或默认浏览器应用。Android 自定义标签页库也是一个受支持的选项。
iOS
iOS 和 macOS 开发者在 WKWebView 中打开授权请求时可能会遇到此错误。开发者应改用 iOS 库，例如 iOS 版 Google 登录或 OpenID Foundation' 的 AppAuth for iOS。
如果 iOS 或 macOS 应用打开嵌入式用户代理中的常规网页链接，并且用户从您的网站导航到 Google 的 OAuth 2.0 授权端点，则网页开发者可能会遇到此错误。开发者应允许操作系统的默认链接处理程序（包括通用链接处理程序或默认浏览器应用）中打开常规链接。SFSafariViewController 库也是一个受支持的选项。
org_internal
请求中的 OAuth 客户端 ID 属于限制对特定 Google Cloud 组织中的 Google 帐号的访问的项目。如需详细了解此配置选项，请参阅“设置 OAuth 同意屏幕”帮助文章中的用户类型部分。
origin_mismatch
发起授权请求的 JavaScript 的架构、网域和/或端口可能与为 OAuth 客户端 ID 注册的授权 JavaScript 来源 URI 不匹配。查看 Google API ConsoleCredentials 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 来源。
第 4 步：处理 OAuth 2.0 服务器响应
JS 客户端库
JavaScript 客户端库会处理来自 Google 授权服务器的响应。如果您设置了监听器，以监控当前登录状态的变化，系统会在用户授予所请求的应用访问权限时调用该函数。
OAuth 2.0 端点
OAuth 2.0 服务器会将响应发送到您的访问令牌请求中指定的 redirect_uri。
如果用户批准请求，响应中将包含访问令牌。如果用户未批准请求，响应中会包含错误消息。系统会在重定向 URI 的哈希代码段上返回访问令牌或错误消息，如下所示：
访问令牌响应：
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
除了
access_token参数之外，fragment 字符串还包含token_type参数（始终设置为Bearer）和expires_in参数（用于指定令牌的生命周期（以秒为单位）。如果在访问令牌请求中指定了state参数，则其值也会包含在响应中。- 错误响应：
https://oauth2.example.com/callback#error=access_denied
OAuth 2.0 服务器响应示例
您可以点击以下链接，请求查看您 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
完成 OAuth 2.0 流程后，系统会将您重定向到 http://localhost/oauth2callback。除非本地机器在本地地址提供文件，否则该网址会产生 404 NOT FOUND 错误。后续步骤详细介绍了当用户重定向回您的应用时在 URI 中返回的信息。
调用 Google API
JS 客户端库
在您的应用获得访问令牌后，您可以使用 JavaScript 客户端库代表用户发出 API 请求。客户端库会代为管理访问令牌，您无需执行任何特殊操作即可在请求中发送访问令牌。
客户端库支持两种调用 API 方法的方式。如果您已加载发现文档，该 API 会为您定义特定于方法的函数。您还可以使用 gapi.client.request 函数调用 API 方法。以下两个代码段展示了适用于 Drive API 的 about.get 方法的这些选项。
// Example 1: Use method-specific function
var request = gapi.client.drive.about.get({'fields': 'user'});
// Execute the API request.
request.execute(function(response) {
console.log(response);
});
// Example 2: Use gapi.client.request(args) function
var request = gapi.client.request({
'method': 'GET',
'path': '/drive/v3/about',
'params': {'fields': 'user'}
});
// Execute the API request.
request.execute(function(response) {
console.log(response);
});
OAuth 2.0 端点
在您的应用获得访问令牌后，您可以使用该令牌代表指定的用户帐号调用 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
JavaScript 示例代码
以下代码段演示了如何使用 CORS（跨域资源共享）向 Google API 发送请求。此示例未使用适用于 JavaScript 的 Google API 客户端库。不过，即使您使用的不是客户端库，该库的文档中的 CORS 支持指南仍可能有助于您更好地了解这些请求。
在此代码段中，access_token 变量表示您代表授权用户发出的 API 请求的令牌。完整示例演示了如何将该令牌存储在浏览器的本地存储空间中，并在发出 API 请求时检索该令牌。
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) {
console.log(xhr.response);
};
xhr.send(null);
完整示例
JS 客户端库
示例代码演示
本部分包含代码示例的运行演示，演示了示例代码在实际应用中的运行方式。获得应用授权后，它会列在与您的 Google 帐号关联的应用中。该应用名为适用于 Google API 文档的 OAuth 2.0 演示。同样，如果您撤消访问权限并刷新该网页，那么该应用将不会再列出。
请注意，此应用请求访问 https://www.googleapis.com/auth/drive.metadata.readonly 范围。我们申请访问权限的目的只是为了演示如何在 JavaScript 应用中启动 OAuth 2.0 流程。
此应用未发出任何 API 请求。
JavaScript 示例代码
如上所示，此代码示例适用于加载 JavaScript 版 Google API 客户端库并启动 OAuth 2.0 流程的网页（应用）。该页面会显示以下任一内容：
- 一个让用户登录应用的按钮。如果用户之前未向应用授权，则该应用会启动 OAuth 2.0 流程。
- 两个可让用户退出应用或撤消之前授予应用访问权限的按钮。如果您退出应用，则未撤消向应用授予的访问权限。您需要重新登录，应用才能代表您发出其他授权请求，不过下次使用时，您无需再次授予访问权限。不过，如果您撤消访问权限，则需要再次授予访问权限。
您还可以通过 Google 帐号的权限页面撤消对应用的访问权限。该应用被列为 Google API 文档的 OAuth 2.0 演示。
<script>
var GoogleAuth;
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
function handleClientLoad() {
// Load the API's client and auth2 modules.
// Call the initClient function after the modules load.
gapi.load('client:auth2', initClient);
}
function initClient() {
// In practice, your app can retrieve one or more discovery documents.
var discoveryUrl = 'https://www.googleapis.com/discovery/v1/apis/drive/v3/rest';
// Initialize the gapi.client object, which app uses to make API requests.
// Get API key and client ID from API Console.
// 'scope' field specifies space-delimited list of access scopes.
gapi.client.init({
'apiKey': 'YOUR_API_KEY',
'clientId': 'YOUR_CLIENT_ID',
'discoveryDocs': [discoveryUrl],
'scope': SCOPE
}).then(function () {
GoogleAuth = gapi.auth2.getAuthInstance();
// Listen for sign-in state changes.
GoogleAuth.isSignedIn.listen(updateSigninStatus);
// Handle initial sign-in state. (Determine if user is already signed in.)
var user = GoogleAuth.currentUser.get();
setSigninStatus();
// Call handleAuthClick function when user clicks on
// "Sign In/Authorize" button.
$('#sign-in-or-out-button').click(function() {
handleAuthClick();
});
$('#revoke-access-button').click(function() {
revokeAccess();
});
});
}
function handleAuthClick() {
if (GoogleAuth.isSignedIn.get()) {
// User is authorized and has clicked "Sign out" button.
GoogleAuth.signOut();
} else {
// User is not signed in. Start Google auth flow.
GoogleAuth.signIn();
}
}
function revokeAccess() {
GoogleAuth.disconnect();
}
function setSigninStatus() {
var user = GoogleAuth.currentUser.get();
var isAuthorized = user.hasGrantedScopes(SCOPE);
if (isAuthorized) {
$('#sign-in-or-out-button').html('Sign out');
$('#revoke-access-button').css('display', 'inline-block');
$('#auth-status').html('You are currently signed in and have granted ' +
'access to this app.');
} else {
$('#sign-in-or-out-button').html('Sign In/Authorize');
$('#revoke-access-button').css('display', 'none');
$('#auth-status').html('You have not authorized this app or you are ' +
'signed out.');
}
}
function updateSigninStatus() {
setSigninStatus();
}
</script>
<button id="sign-in-or-out-button"
style="margin-left: 25px">Sign In/Authorize</button>
<button id="revoke-access-button"
style="display: none; margin-left: 25px">Revoke access</button>
<div id="auth-status" style="display: inline; padding-left: 25px"></div><hr>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script async defer src="https://apis.google.com/js/api.js"
onload="this.onload=function(){};handleClientLoad()"
onreadystatechange="if (this.readyState === 'complete') this.onload()">
</script>
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 地址不受此规则约束。 |
| 网域 |
“googleusercontent.com”。goo.gl），除非应用拥有该域名。 |
| 用户信息 |
JavaScript 来源不能包含 userinfo 子组件。 |
| 路径 |
JavaScript 来源不能包含路径组件。 |
| 查询 |
JavaScript 来源不能包含查询组件。 |
| fragment |
JavaScript 来源不能包含 fragment 组件。 |
| 字符 |
JavaScript 来源不能包含某些字符，包括：
|
增量授权
在 OAuth 2.0 协议中，您的应用会请求访问由范围标识的资源。我们建议采用一种最佳的用户体验做法，以便在您需要时请求资源授权。为了实现这种做法，Google 的授权服务器支持增量授权。此功能允许您根据需要请求范围，如果用户为新范围授予权限，则会返回授权代码，该代码可能会替换为用户授予项目的所有范围的令牌。
例如，如果应用允许用户登录试听音乐和创建合辑，在登录时可能需要使用非常少的资源，可能只不过是登录人的姓名。不过，保存已完成的合辑需要访问其 Google 云端硬盘。大多数人会发现，如果在应用实际需要时只请求访问他们的 Google 云端硬盘，那会是很自然的做法。
在这种情况下，应用在登录时，可能会请求 openid 和 profile 范围来执行基本登录，然后在第一次请求时请求 https://www.googleapis.com/auth/drive.file 范围以保存组合。
以下规则适用于从增量授权中获取的访问令牌：
- 该令牌可用于访问与合并后的合并授权中的任意范围相对应的资源。
- 当您使用刷新授权组合获得访问令牌时，访问令牌将代表合并授权，可用于响应中的任何
scope值。 - 合并授权包括用户授权给 API 项目的所有范围，即使授权是由不同的客户端提出的。例如，如果用户使用应用的桌面客户端向一个范围授予访问权限，然后通过移动客户端向同一应用授予另一个范围，则合并授权将同时包含这两个范围。
- 如果您撤消代表合并授权的令牌，则代表关联用户对所有授权范围的访问权限会同时被撤消。
以下代码示例展示了如何向现有访问令牌添加范围。此方法使您的应用无需管理多个访问令牌。
JS 客户端库
如需为现有访问令牌添加范围，请调用 GoogleUser.grant(options) 方法。options 对象用于标识您要授予访问权限的其他范围。
// Space-separated list of additional scope(s) you are requesting access to.
// This code adds read-only access to the user's calendars via the Calendar API.
var NEW_SCOPES = 'https://www.googleapis.com/auth/calendar.readonly';
// Retrieve the GoogleUser object for the current user.
var GoogleUser = GoogleAuth.currentUser.get();
GoogleUser.grant({'scope': NEW_SCOPES});
OAuth 2.0 端点
如需向现有访问令牌添加范围，请在向 Google 的 OAuth 2.0 服务器发送的请求中添加 include_granted_scopes 参数。
以下代码段演示了如何做到这一点。此代码段假定您已在浏览器的本地存储空间中存储了访问令牌有效的范围。（完整示例代码通过在浏览器的本地存储空间中设置 oauth2-test-params.scope 属性，存储访问令牌有效的范围列表。）
代码段会将访问令牌有效的范围与您的特定查询要使用的范围进行比较。如果访问令牌未涵盖该范围，系统会启动 OAuth 2.0 流程。
这里的 oauth2SignIn 函数与第 2 步中提供的函数相同（稍后将在完整示例中提供）。
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
var scopes = params['scope'].split(' ');
for (var s = 0; s < scopes.length; s++) {
if (SCOPE == scopes[s]) {
current_scope_granted = true;
}
}
}
if (!current_scope_granted) {
oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
// Since you already have access, you can proceed with the API request.
}
撤消令牌
在某些情况下，用户可能会想要撤消对应用的访问权限。用户可以通过访问帐号设置撤消访问权限。如需了解详情，请参阅撤消有权访问您帐号的第三方网站或应用的应用部分的支持文档。
应用还可以以编程方式撤消授予它的访问权限。在用户退订、移除应用或应用所需的 API 资源发生了显著变化的情况下，程序化撤消非常重要。也就是说，移除流程的一部分可能包含 API 请求，以确保移除之前授予应用的权限。
JS 客户端库
如需以编程方式撤消令牌，请调用 GoogleAuth.disconnect()：
GoogleAuth.disconnect();
OAuth 2.0 端点
为了以编程方式撤消令牌，您的应用会向 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 以及错误代码。
以下 JavaScript 代码段展示了如何在不使用 JavaScript 版 Google API 客户端库的情况下，撤消 JavaScript 中的令牌。由于 Google 用于撤消令牌的 OAuth 2.0 端点不支持跨域资源共享 (CORS)，因此代码会创建一个表单，并将表单提交到端点，而不是使用 XMLHttpRequest() 方法发布请求。
function revokeAccess(accessToken) {
// Google's OAuth 2.0 endpoint for revoking access tokens.
var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
// Create <form> element to use to POST data to the OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'post');
form.setAttribute('action', revokeTokenEndpoint);
// Add access token to the form so it is set as value of 'token' parameter.
// This corresponds to the sample curl request, where the URL is:
// https://oauth2.googleapis.com/revoke?token={token}
var tokenField = document.createElement('input');
tokenField.setAttribute('type', 'hidden');
tokenField.setAttribute('name', 'token');
tokenField.setAttribute('value', accessToken);
form.appendChild(tokenField);
// Add form to page and submit it to actually revoke the token.
document.body.appendChild(form);
form.submit();
}