用戶端網路應用程式的 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&
 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();
}

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 傳回的資訊。

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>

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 程式碼片段顯示如何在不使用 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();
}