針對用戶端網頁應用程式使用 OAuth 2.0

OAuth 2.0 端點

產生網址，透過位於 https://accounts.google.com/o/oauth2/v2/auth 的 Google OAuth 2.0 端點要求存取權。這個端點可透過 HTTPS 存取，因此系統拒絕使用一般 HTTP 連線。

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

重新導向至 Google 授權伺服器的範例

以下範例網址顯示了換行符號及方便閱讀的空格。該網址會要求存取範圍，以便擷取使用者的 YouTube 資料。這項服務使用漸進式授權 (include_granted_scopes=true)，確保新的存取權杖涵蓋使用者先前授予應用程式存取權的任何範圍。本範例中也設定了其他幾個參數。

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 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/youtube.force-ssl',
                '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 參數以外，片段字串也包含一律設為 Bearer 的 token_type 參數，以及指定權杖生命週期的 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%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 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 的呼叫 (例如呼叫 YouTube Live Streaming API 時)。

請注意，YouTube Live Streaming API 不支援服務帳戶流程。由於無法將服務帳戶連結至 YouTube 帳戶，因此嘗試透過此流程授權要求時，會產生 NoLinkedYouTubeAccount 錯誤。

如要試用所有 Google API 及查看其範圍，請前往 OAuth 2.0 Playground。

HTTP GET 範例

使用 Authorization: Bearer HTTP 標頭呼叫 liveBroadcasts.list 端點 (YouTube Live Streaming API) 的呼叫可能如下所示。請注意，您必須指定自己的存取權杖：

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

以下示範如何使用 access_token 查詢字串參數，為通過驗證的使用者呼叫相同的 API：

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl 個樣本

您可以使用 curl 指令列應用程式測試這些指令。以下為使用 HTTP 標頭選項的範例 (建議)：

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

或者，您也可以使用查詢字串參數選項：

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

JavaScript 程式碼範例

下列程式碼片段示範如何使用 CORS (跨源資源共享) 將要求傳送至 Google API。本例未使用 JavaScript 的 Google API 用戶端程式庫，不過，即使您並未使用用戶端程式庫，該程式庫說明文件中的 CORS 支援指南也許能協助您進一步瞭解這些要求。

在這個程式碼片段中，access_token 變數代表您取得的權杖，用來代表授權使用者提出 API 要求。完整範例示範如何將權杖儲存至瀏覽器的本機儲存空間，並在提出 API 要求時擷取該權杖。

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
    '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/youtube.force-ssl 範圍。
2. 授予 (或拒絕) 對一或多個要求範圍的存取權後，系統會將使用者重新導向至原始網頁，以便剖析片段 ID 字串中的存取權杖。

3. 這個網頁會使用存取權杖發出範例 API 要求。

   這個 API 要求會呼叫 YouTube Data API 的 liveBroadcasts.list 方法，擷取授權使用者 YouTube 頻道的影片廣播清單。

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

  // 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']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
          '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() {
    // 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/youtube.force-ssl',
                  '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 端點

在本範例中，除了使用者已授予應用程式的任何其他存取權，發出呼叫的應用程式也會要求擷取使用者的 YouTube 資料，以擷取使用者的 YouTube 資料。

如要將範圍新增至現有的存取權杖，請在對 Google OAuth 2.0 伺服器發出的要求中加入 include_granted_scopes 參數。

下列程式碼片段說明如何執行這項作業。程式碼片段假設您已將存取權杖有效的範圍儲存在瀏覽器本機儲存空間中。(完整範例程式碼會儲存瀏覽器本機儲存空間中的 oauth2-test-params.scope 屬性，藉此儲存存取權杖有效的範圍清單)。

程式碼片段會比較存取權杖的有效範圍，並針對特定查詢使用的範圍。如果存取權杖未涵蓋該範圍，OAuth 2.0 流程就會啟動。這裡的 oauth2SignIn 函式與步驟 2 中的函式相同 (將於稍後的完整範例中提供)。

var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
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();
}