OAuth 2.0 for Client-side Web Applications

OAuth 2.0的客户端Web应用程序

本文介绍了如何从一个JavaScript的Web应用程序实现的OAuth 2.0授权访问谷歌的API。的OAuth 2.0允许用户共享特定的数据与应用程序，同时保持他们的用户名，密码和其他私人信息。例如，应用程序可以使用OAuth 2.0从用户那里获得许可，以存储在他们的谷歌驱动器的文件。

这OAuth 2.0用户流量被称为隐性补助流。它是专为应用程序访问API仅在用户存在于应用程序。这些应用程序不是能够存储的机密信息。

在这个流程中，您的应用程序打开一个谷歌的网址，使用查询参数，以确定您的应用程序和API访问的应用程序需要的类型。您可以在当前浏览器窗口或弹出打开URL。用户可以通过谷歌认证，并授予所要求的权限。谷歌然后将用户重定向回您的应用程序。重定向包含的访问令牌，您的应用验证，然后使用使API请求。

注：由于得到执行正确的安全隐患，我们强烈建议您与谷歌的OAuth 2.0端点交互时使用OAuth 2.0库。它是利用他人提供的精心调试代码的最佳实践，这将有助于保护您和您的用户。看到 JS客户端库本文档中的选项卡为例子，说明如何授权使用谷歌API客户端JavaScript库的用户。

先决条件

启用专案的API

调用谷歌API的应用程序需要启用API控制台这些API。为了能够为您的项目适当的API：

1. 打开库的API控制台页面。
2. 选择与应用程序相关的项目。创建一个项目，如果你没有一个了。
3. 使用图书馆页面，找到每个API应用程序将使用。点击每个API并启用它为您的项目。

创建授权证书

任何应用程序使用OAuth 2.0访问谷歌的API必须具有识别应用到谷歌的OAuth 2.0服务器授权证书。下面的步骤说明如何为项目创建的凭据。然后，您的应用程序可以使用凭据来访问API，您已经为该项目启用。

1. 打开证书页面的API控制台英寸
2. 点击创建凭证> OAuth用户端ID。
3. 完成表格。设置应用程序类型Web application。使用JavaScript的应用程序，使谷歌授权的API请求都必须指定授权的JavaScript源。起源识别从您的应用程序可以发送API请求的域。

确定访问范围

作用域使您的应用程序只对需要同时还使用户能够控制访问的，他们授予您的应用程序数量的资源请求的访问。因此，有可能是请求的范围的数量和获得用户同意的可能性之间存在反比关系。

你开始实施的OAuth 2.0授权之前，我们建议您识别范围，你的应用程序将需要访问权限的。

该的OAuth 2.0 API范围 文档包含范围，您可以使用访问谷歌的API的完整列表。

如果您的公共应用利用范围来某些用户数据允许访问，它必须完成验证过程。如果您看到未验证的应用程序在屏幕上测试您的应用程序时，您必须提交验证请求将其删除。了解更多关于 未经验证的应用程序 ，并得到解答 关于应用验证常见问题在帮助中心。

获得的OAuth 2.0访问令牌

下列步骤显示了与谷歌的OAuth 2.0服务器应用程序交互如何获得用户的同意执行代表用户的API请求。您的应用程序必须有许可，然后才能执行需要用户授权谷歌的API请求。

步骤1：配置客户对象

如果您使用的是谷歌的API客户端JavaScript库来处理OAuth 2.0流程，第一步是配置gapi.auth2 和gapi.client对象。这些对象使应用程序能够获得用户授权和进行授权的API请求。

客户对象识别您的应用程序请求允许访问的范围。这些值告知同意画面，谷歌显示给用户。在选择接入范围部分提供了有关如何确定的作用域应用程序应请求允许访问信息。

JS客户端库 OAuth 2.0用户端点

JavaScript客户端库简化了授权过程的许多方面：

1. 它可以为谷歌的授权服务器重定向URL，并提供引导用户到该网址的方法。
2. 它处理从服务器返回到您的应用程序的重定向。
3. 它验证授权服务器返回的访问令牌。
4. 它存储令牌授权服务器发送到您的应用程序，并检索它，当你的应用程序随后让授权的API调用访问。

下面的代码段是从一个摘录完整的例子稍后在本文档中示出。此代码初始化的 gapi.client对象，你的应用程序将在以后使用来进行API调用。当创建对象，该gapi.auth2 对象，你的应用程序使用，检查和监控用户的授权状态，也被初始化。

要将呼叫gapi.client.init指定以下字段：

• 该apiKey和clientId值来指定应用程序的授权证书。正如所讨论的 创建授权凭证 部分，可以在API控制台来获得这些值。请注意，clientId如果您的应用程序进行授权的API请求是必需的。应用程序，只有让未经授权的请求，只需指定一个API密钥。

• 该scope字段指定的空格分隔列表 访问作用域相对应的资源，你的应用程序需要访问。这些值告知同意画面，谷歌显示给用户。

  我们建议，以授权您的应用程序请求访问上下文作用域只要有可能。通过请求访问用户数据的情况下，通过增量授权，你帮助用户更容易理解为什么您的应用程序需要被请求的访问。

• 该discoveryDocs字段标识列表API发现的文件，你的应用程序使用。一个发现文档描述了表面的API，包括其资源模式和JavaScript客户端库使用该信息来生成方法应用程序可以使用。在这个例子中，代码检索谷歌云端硬盘API第3版的发现文档。

在之后gapi.client.init调用完成，该代码将 GoogleAuth变量来标识谷歌验证对象。最后，该代码将调用一个函数监听器，当用户的登录状态的变化。（该函数不会在代码段中定义。）

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);
  });
}

 

第2步：重定向到谷歌的OAuth 2.0服务器

请求允许访问的用户数据，将用户重定向到谷歌的OAuth 2.0服务器。

JS客户端库 OAuth 2.0用户端点

调用GoogleAuth.signIn()方法将用户定向到谷歌的授权服务器。

GoogleAuth.signIn();

 

在实践中，你的应用程序可能会设置一个布尔值，以确定是否调用signIn()试图进行API调用方法之前。

下面的代码片段演示了如何启动用户授权流程。请注意有关代码段以下几点：

• 所述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;
  }
}

 

第3步：谷歌会提示用户的同意

在这个步骤中，用户将决定是否给予您的应用程序所请求的访问。在这个阶段，谷歌将显示一个窗口同意，显示您的应用程序的名称和谷歌API服务，它请求允许与用户的授权凭证的访问。然后，用户可以同意或拒绝授予访问您的应用程序。

您的应用程序并不需要在这个阶段，因为它等待来自谷歌的OAuth 2.0服务器指示访问是否被授予响应做任何事情。该响应在下面的步骤进行说明。

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

JS客户端库 OAuth 2.0用户端点

JavaScript客户端库处理来自谷歌的授权服务器的响应。如果设置一个监听监视当前用户的更改登录状态下，该功能是当用户授予请求访问的应用程序调用。

称谷歌的API

JS客户端库 OAuth 2.0用户端点

您的应用程序获得访问令牌后，您可以使用JavaScript客户端库，使代表用户的API请求。客户端库管理令牌为您的访问，你不需要做什么特别的在请求发送。

客户端库支持两种方式来调用API方法。如果您装入一个发现文档，该API将定义你的方法，特定的功能。您还可以使用该 gapi.client.request 函数来调用的API方法。下面的两个片段演示这些选项的驱动器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);
});

 

完整示例

JS客户端库 OAuth 2.0用户端点

示例代码演示

本节包含如下证明代码示例的工作演示如何在实际的应用程序代码的行为。您授权的应用程序后，将在其中列出 连接到您的谷歌帐户的应用程序。这款应用程序名为OAuth 2.0用户演示了谷歌API文档。同样，如果您取消访问，并刷新该页面，该应用程序将不再上市。

请注意，这个应用程序请求访问https://www.googleapis.com/auth/drive.metadata.readonly 范围。该访问请求只是为了演示如何启动在JavaScript应用程序中的OAuth 2.0流。这个应用程序不作任何API请求。

JavaScript的代码示例

如上所示，此代码示例为页（一个应用程序），该加载谷歌API客户端库JavaScript和发起的OAuth 2.0流动。该页面显示两种：

• 一个按钮，可以让用户登录到应用程序。如果用户以前未授权的应用程序，然后应用程序启动的OAuth 2.0流。

• 两个按钮，允许用户或者登出应用程式或撤销先前授予应用程序的访问。如果您的应用程序的退出，你还没有撤销授予应用程序的访问。您需要再次登录之前，应用程序可以以自己的名义其它授权的请求，但你不会有您所使用的应用程序，下一次再授予访问权限。但是，如果取消访问，那么你需要重新授予访问权限。

您也可以撤销通过访问应用程序 的权限为您的谷歌帐户页面。该应用程序被列为OAuth 2.0用户演示了谷歌API文档。

Sign In/Authorize
Revoke access

 

增量授权

在OAuth 2.0协议，您的应用程序请求授权访问的资源，这是由范围确定。它被认为是一个最好的用户体验实践请求授权在你需要他们的时间资源。为了实现这一做法，谷歌的授权服务器支持增量授权。此功能可让您请求范围在需要的时候，如果用户授予权限，这些范围添加到令牌为用户现有的访问。

例如，一个应用程序，让人们样品的音乐曲目，并创建混音可能在登录的时候，也许没有什么比在签字人的名字需要很少的资源。然而，保存完成混音需要访问他们的谷歌驱动器。大多数人会觉得很自然，如果他们只被要求访问其谷歌云端应用程序确实需要它的时候。

在这种情况下，在登录时的应用程式可能要求的profile 范围中签执行基本的，再后来要求 https://www.googleapis.com/auth/drive.file在第一次请求保存混合的时间范围。

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

• 该令牌可以被用于对应于任何滚入新的组合授权作用域接入资源。
• 当您使用令牌的联合授权来获得访问令牌，令牌代表联合授权，可以使用任何范围的访问刷新。
• 组合授权包括用户授予即使从不同的客户被要求拨款的API项目的所有范围。例如，如果用户通过移动客户端使用一个应用程序的桌面客户端授予访问一个范围，然后给予另一种范围相同的应用程序，将合并的授权将包括作用域。
• 如果要撤销令牌代表联合授权，访问所有的授权的范围代表相关用户的同时撤销。

下面的代码示例说明如何将范围添加到现有的访问令牌。这种方法允许你的应用程序需要管理多个访问令牌避免的。

JS客户端库 OAuth 2.0用户端点

为了范围添加到现有的访问令牌，调用该 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});

 

撤销令牌

在某些情况下，用户可能希望撤销给应用程序的访问。用户可以通过撤销访问接入 帐户设置。也可以为应用程序编程撤销给它的访问。编程撤销是重要的情况下在用户退订或删除的应用程序。换言之，在去除过程的一部分可以包括API请求，以确保许可所述应用程序的权限被除去。

JS客户端库 OAuth 2.0用户端点

要以编程方式撤销令牌，电话GoogleAuth.disconnect()：

GoogleAuth 。断开（）;