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

OAuth 2.0 端点

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

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

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

以下示例网址包含换行符和空格，以便于阅读。

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.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 代码段展示了如何在不使用 Google API JavaScript 客户端库的情况下在 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 https://www.googleapis.com/auth/calendar.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();
}

OAuth 2.0 端点

OAuth 2.0 服务器向访问令牌请求中指定的 redirect_uri 发送响应。

如果用户批准了请求，响应中就会包含访问令牌。如果用户未批准请求，响应中会包含错误消息。访问令牌或错误消息会在重定向 URI 的哈希 fragment 中返回，如下所示：

• 访问令牌响应：

  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 云端硬盘中文件的元数据，以及查看您 Google 日历活动的读取权限：

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.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 中返回的信息。

OAuth 2.0 端点

如需检查用户是否已向您的应用授予对特定范围的访问权限，请检查访问令牌响应中的 scope 字段。access_token 授予的访问范围，表示为以空格分隔且区分大小写的字符串列表。

例如，以下访问令牌响应示例表明，用户已向您的应用授予对只读 Drive 活动和日历活动权限的访问权限：

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

OAuth 2.0 端点

在应用获取访问令牌后，如果已授予 API 所需的访问范围，您可以使用该令牌代表给定用户账号调用 Google 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 端点（即云端硬盘文件 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);

OAuth 2.0 端点

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

对于 OAuth 2.0 流程，该页面会按照以下步骤操作：

1. 它会将用户定向到 Google 的 OAuth 2.0 服务器，该服务器会请求访问 https://www.googleapis.com/auth/drive.metadata.readonly 和 https://www.googleapis.com/auth/calendar.readonly 范围。
2. 授予（或拒绝）对一个或多个请求的范围的访问权限后，系统会将用户重定向到原始页面，该页面会从 fragment 标识符字符串解析访问令牌。
3. 该页面会检查用户已向应用授予哪些范围的访问权限。

4. 如果用户已授予对请求的 scope() 的访问权限，则该页面会使用访问令牌发出示例 API 请求。

   API 请求会调用 Drive API 的 about.get 方法，以检索已获授权用户的 Google 云端硬盘账号的相关信息。

5. 如果请求成功执行，API 响应会记录在浏览器的调试控制台中。

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

如需在本地运行此代码，您需要为 YOUR_CLIENT_ID 和 YOUR_REDIRECT_URI 变量设置与您的授权凭据对应的值。YOUR_REDIRECT_URI 变量应设置为与网页提供的网址相同。此值必须与 OAuth 2.0 客户端的已授权重定向 URI 之一完全匹配，您可以在 API Console Credentials page中配置这些 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';

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

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // 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']) { 
      // User authorized the request. Now, check which scopes were granted.
      if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
        // User authorized read-only Drive activity permission.
        // Calling the APIs, etc.
        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 {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
        console.log('User did not authorize read-only Drive activity permission.');
      }

      // Check if user authorized Calendar read permission.
      if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
        console.log('User authorized Calendar read permission.');
      }
      else {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
        console.log('User did not authorize Calendar read permission.');
      } 
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // 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 https://www.googleapis.com/auth/calendar.readonly',
                  'state': state,
                  '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>

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.
}

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 代码段展示了如何在不使用 Google API JavaScript 客户端库的情况下在 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();
}