用戶端網路應用程式的 OAuth 2.0

本文說明如何實作 OAuth 2.0 授權，以便透過 JavaScript 網頁應用程式存取 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 Identity Services 的權杖模型，這是根據 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，然後按一下「Enable」按鈕。
  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. 按一下 [Create credentials] (建立憑證) > [OAuth client ID] (OAuth 用戶端 ID)。
  3. 選取「Web application」(網頁應用程式) 應用程式類型。
  4. 完整填寫表單。使用 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 端點

產生網址，透過 https://accounts.google.com/o/oauth2/v2/auth 的 Google OAuth 2.0 端點要求存取權。這個端點可透過 HTTPS 存取，但拒絕的 HTTP 連線會遭到拒絕。

Google 授權伺服器支援下列網路伺服器應用程式查詢字串參數：

參數
client_id 必要

應用程式的用戶端 ID。您可以在 API Console Credentials page中找到這個值。
redirect_uri 必要

決定 API 伺服器在使用者完成授權流程後將使用者重新導向的位置。這個值必須與您在用戶端 API Console Credentials page中設定的 OAuth 2.0 用戶端其中一個授權重新導向 URI 完全相符。如果這個值與提供的 client_id 的授權重新導向 URI 不符，您會收到 redirect_uri_mismatch 錯誤。

請注意，http 或 https 配置、大小寫和結尾的斜線 (「/」) 必須全部相符。
response_type 必要

JavaScript 應用程式必須將參數值設為 token。這個值會指示 Google 授權伺服器在授權程序完成後，將使用者重新導向 URI 的 ID 組合以 name=value 配對的形式 (#) 傳回。
scope 必要

以空格分隔的範圍清單，識別應用程式可以代表使用者存取的資源。這些值會通知 Google 向使用者顯示的同意畫面。

存取權範圍可讓應用程式僅要求存取必要資源的權限，並讓使用者控制對應用程式授予的存取權量。因此，要求的範圍數量和取得使用者同意聲明的可能性之間存在反向關係。

建議您盡可能要求應用程式在相關情境中取得授權範圍。透過漸進式授權功能，您可以要求在情境中存取使用者資料，讓使用者更容易瞭解應用程式需要該權限的原因。
state 建議使用

指定應用程式用於保留授權要求狀態與授權伺服器回應的任何字串值。使用者同意或拒絕應用程式的存取權要求後，伺服器會傳回您用 redirect_uri 網址片段 ID (#) 中傳送的 name=value 組合確切的值。

這個參數有多種用途，例如引導使用者前往應用程式中的正確資源、傳送 Nonce，以及減少偽造的跨網站要求。由於可以猜測 redirect_uri，使用 state 值可以保證傳入連線是驗證要求的結果。如果您會產生隨機字串或編碼 Cookie 或其他會擷取用戶端狀態的值，則可驗證回應，進一步確保要求和回應來自同一個瀏覽器，藉此防範跨網站偽造要求等攻擊。如要瞭解如何建立及確認 state 權杖，請參閱 OpenID Connect 說明文件。
include_granted_scopes 選用

允許應用程式讓應用程式使用漸進式授權功能，要求額外的內容範圍。如果將這個參數的值設為 true，且已授予授權要求，則新的存取權杖也會涵蓋使用者先前授予應用程式存取權的任何範圍。如需範例，請參閱增量授權一節。
login_hint 選用

如果應用程式知道要嘗試驗證的使用者，可以使用這個參數為 Google 驗證伺服器提供提示。伺服器會使用提示來填寫登入表單中的電子郵件欄位，或選取適當的多重登入工作階段來簡化登入流程。

將參數值設為電子郵件地址或 sub ID，這相當於使用者的 Google ID。
prompt 選用

以空格分隔的提示清單會向使用者顯示。如未指定這個參數，系統只會在專案首次要求存取權時提示使用者。詳情請參閱「 提示使用者重新同意」。

可能的值為：

none 不要顯示任何驗證或同意畫面。不可指定其他值。
consent 提示使用者徵求同意。
select_account 提示使用者選取帳戶。

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.webkit.WebView 中開啟授權要求時，Android 開發人員可能會收到這則錯誤訊息。開發人員應改用 Android 程式庫，例如 Android 適用的 Google 登入或 OpenID Foundation 的 AppAuth for Android。

如果 Android 應用程式在內嵌的使用者代理程式中開啟一般網頁連結，且使用者從您的網站前往 Google 的 OAuth 2.0 授權端點，網頁程式可能會遇到這個錯誤。開發人員應允許作業系統在作業系統的預設連結處理常式中開啟一般連結，包括 Android 應用程式連結處理常式或預設的瀏覽器應用程式。另外，Android Custom Tabs 程式庫也提供資料庫選項。

iOS

在 WKWebView 中開啟授權要求時，iOS 和 macOS 開發人員可能會發生這個錯誤。開發人員應改用 iOS 程式庫，例如 iOS 適用的 Google 登入或 OpenID Foundation 的 AppAuth iOS 版。

當 iOS 或 macOS 應用程式在內嵌的使用者代理程式中開啟一般網頁連結，且使用者從您的網站前往 Google 的 OAuth 2.0 授權端點時，網頁程式可能會發生這個錯誤。開發人員應允許在作業系統的預設連結處理常式中開啟一般連結，其中包含通用連結處理常式或預設的瀏覽器應用程式。另外，您也可以使用 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) 流程。如需更新整合作業，請參閱遷移指南。

步驟 3：處理 OAuth 2.0 伺服器回應

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 參數以外，片段字串也包含 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

OAuth 2.0 端點

應用程式取得存取權杖後，如果您授予 API 要求的存取權範圍，就可以使用這個權杖代表指定使用者帳戶對 Google API 進行呼叫。方法是在 API 要求中加入存取權杖，方法是加入 access_token 查詢參數或 Authorization HTTP 標頭 Bearer 值。建議盡可能使用 HTTP 標頭，因為查詢字串通常會顯示在伺服器記錄中。在大部分情況下，您可以使用用戶端程式庫設定呼叫 Google API (例如呼叫 Drive Files API)。

如要試用所有 Google API，請前往 OAuth 2.0 Playground。

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

完整範例

OAuth 2.0 端點

這個程式碼範例示範如何使用 JavaScript 專用的 Google API 用戶端程式庫完成 JavaScript 2.0 流程。程式碼適用於顯示 API 要求按鈕的 HTML 網頁。按一下按鈕，程式碼就會檢查網頁是否將 API 存取權杖儲存在瀏覽器本機儲存空間中。如果是這樣，這類 API 會執行 API 要求。否則，就會啟動 OAuth 2.0 流程。

執行 OAuth 2.0 流程時，該網頁按照下列步驟操作：

  1. 將使用者導向到 Google 的 OAuth 2.0 伺服器，該伺服器會要求存取 https://www.googleapis.com/auth/drive.metadata.readonly 範圍。
  2. 授予 (或拒絕) 一或多個要求範圍的存取權後，系統會將使用者重新導向至原始網頁，並從片段 ID 字串剖析存取權杖。

  3. 網頁會使用存取權杖來建立範例 API 要求。

    API 要求會呼叫 Drive API 的 about.get 方法，擷取授權使用者的 Google 雲端硬碟帳戶相關資訊。

  4. 如果要求執行成功，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 來源不能包含網址縮短網域 (例如 goo.gl)。
    		•
    使用者資訊

    JavaScript 來源不得包含使用者資訊子元件。
    路徑

    JavaScript 來源不得包含路徑元件。
    查詢

    JavaScript 來源不得包含查詢元件。
    Fragment

    JavaScript 來源不得包含片段元件。
    字元 JavaScript 來源不能包含特定字元，包括：
    • 萬用字元 ('*')
    • 不可列印的 ASCII 字元
    • 百分比編碼無效 (未遵守百分比符號格式網址編碼，後面接著兩個十六進位數字的任何百分比編碼)
    • 空值字元 (經過編碼的空值，例如%00、%C0%80)

    遞增授權

    在 OAuth 2.0 通訊協定中，您的應用程式會要求存取資源 (根據範圍確認)。在所需資源中要求資源授權是最佳做法。如要啟用這項功能，Google 的授權伺服器支援漸進式授權。這項功能可讓您視需要要求範圍，如果使用者授予新範圍的權限，則會傳回授權碼，此權杖可能會針對使用者授予專案的所有範圍進行交換。

    舉例來說，允許使用者以音樂曲目取樣及建立組合的應用程式，可能必須在登入過程中只取得極少的資源 (不管登入者的名稱為何)。不過，如要儲存已完成的組合，則需要存取他們的 Google 雲端硬碟。如果應用程式只在實際需要時才要求存取 Google 雲端硬碟，大多數使用者都會感到很自然。

    在此情況下，應用程式會在登入時要求 openid 和 profile 範圍來執行基本登入作業，之後則在第一次要求提出請求的 https://www.googleapis.com/auth/drive.file 範圍中要求儲存組合。

    下列規則適用於透過漸進式授權取得的存取權杖：

    • 這個權杖可用來存取與對應於新授權組合中任何範圍對應的資源。
    • 當您使用合併授權的更新權杖來取得存取權杖時，存取權杖代表合併授權，可用於回應中的所有 scope 值。
    • 合併授權包含使用者授予 API 專案的所有範圍，即使要求來自不同用戶端也一樣。舉例來說，如果使用者透過應用程式的桌面用戶端授予某一個範圍的存取權，然後透過行動用戶端向另一個應用程式授予另一個範圍，那麼合併後的授權就會涵蓋這兩個範圍。
    • 如果您撤銷代表合併授權的權杖，系統會一併撤銷代表相關使用者所有授權範圍的存取權。

    以下程式碼範例顯示如何將範圍新增至現有的存取權杖。如此一來，您的應用程式就不必管理多個存取權杖。

    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 要求，以確保系統會移除先前授予應用程式的權限。

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