使用 OAuth 2.0 處理 JavaScript 網頁應用程式

本文說明如何導入 OAuth 2.0 授權,從 JavaScript 網頁應用程式存取 YouTube Data API。OAuth 2.0 可讓使用者與應用程式共用特定資料,同時保有使用者名稱、密碼和其他資訊的私密性。舉例來說,應用程式可透過 OAuth 2.0 取得權限,以便將影片上傳至使用者的 YouTube 頻道。

這個 OAuth 2.0 流程稱為「隱含授權流程」。它適用於具有實際使用者且存取 API 的應用程式。這類應用程式無法儲存機密資訊。

在本流程中,應用程式會開啟使用查詢參數的 Google 網址,以識別您的應用程式,以及應用程式需要的 API 存取權類型。您可以在目前的瀏覽器視窗或彈出式視窗中開啟網址。使用者可以透過 Google 進行驗證並授予要求的權限。接著,Google 會將使用者重新導向回您的應用程式。重新導向後會包含存取權杖,應用程式驗證後便會使用此權杖提出 API 要求。

Google API 用戶端程式庫和 Google Identity 服務

如果您使用 JavaScript 適用的 Google API 用戶端程式庫向 Google 發出授權呼叫,請使用 Google Identity 服務 JavaScript 程式庫處理 OAuth 2.0 流程。請參閱 Google 身分識別服務的權杖模型,此模型是以 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. 在「媒體庫」頁面中,尋找並啟用 YouTube Data API。找出應用程式要使用的任何其他 API,並啟用這些 API。

建立授權憑證

凡是使用 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 授權之前,建議您先找出應用程式需要權限存取的範圍。

YouTube Data API 第 3 版使用下列範圍:

狙擊鏡
https://www.googleapis.com/auth/youtube管理您的 YouTube 帳戶
https://www.googleapis.com/auth/youtube.channel-memberships.creator查看您現有的有效頻道會員清單,以及這些會員目前的級別和成為會員的時間點
https://www.googleapis.com/auth/youtube.force-ssl查看、編輯並永久刪除您的 YouTube 影片、評分、留言和字幕
https://www.googleapis.com/auth/youtube.readonly查看您的 YouTube 帳戶
https://www.googleapis.com/auth/youtube.upload管理您的 YouTube 影片
https://www.googleapis.com/auth/youtubepartner查看及管理您在 YouTube 上的元素和相關內容
https://www.googleapis.com/auth/youtubepartner-channel-audit查看您的 YouTube 頻道中與 YouTube 合作夥伴稽核程序相關的私人資訊

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 錯誤。

請注意,httphttps 配置、大小寫和結尾斜線 (「/」) 必須全部相符。

response_type 必填

JavaScript 應用程式必須將參數值設為 token。這個值會指示 Google 授權伺服器在 URI (#) 片段 ID 的片段 ID 中以 name=value 配對形式傳回存取權杖,系統會在使用者完成授權程序後將其重新導向。

scope 必填

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

範圍可讓應用程式僅要求存取所需的資源,也能讓使用者控管自己授予應用程式的存取權量。因此,要求的範圍數量與取得使用者同意聲明的可能性之間存在反向關係。

YouTube Data API 第 3 版使用下列範圍:

狙擊鏡
https://www.googleapis.com/auth/youtube管理您的 YouTube 帳戶
https://www.googleapis.com/auth/youtube.channel-memberships.creator查看您現有的有效頻道會員清單,以及這些會員目前的級別和成為會員的時間點
https://www.googleapis.com/auth/youtube.force-ssl查看、編輯並永久刪除您的 YouTube 影片、評分、留言和字幕
https://www.googleapis.com/auth/youtube.readonly查看您的 YouTube 帳戶
https://www.googleapis.com/auth/youtube.upload管理您的 YouTube 影片
https://www.googleapis.com/auth/youtubepartner查看及管理您在 YouTube 上的元素和相關內容
https://www.googleapis.com/auth/youtubepartner-channel-audit查看您的 YouTube 頻道中與 YouTube 合作夥伴稽核程序相關的私人資訊

OAuth 2.0 API 範圍文件提供了可用於存取 Google API 的完整範圍清單。

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

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 授權伺服器的範例

以下的範例網址要求離線存取 (access_type=offline) 的範圍,允許該範圍檢視使用者的 YouTube 帳戶。它會使用漸進式授權,確保新的存取權杖涵蓋使用者之前授予應用程式存取權的任何範圍。網址也會設定必要的 redirect_uriresponse_typeclient_id 參數,以及 state 參數的值。這個網址包含換行符號和空格,方便閱讀。

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 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();
}

步驟 2:Google 提示使用者提供同意聲明

在這個步驟中,使用者決定是否授予應用程式所要求的存取權。在這個階段,Google 會顯示同意視窗,其中會顯示應用程式名稱和要求存取權的 Google API 服務,並提供使用者的授權憑證,以及要授予何種存取權範圍的摘要。接著,使用者可選擇同意授予一或多個應用程式要求的存取權,或拒絕要求。

在這個階段,應用程式不需要採取任何行動,因為會等候 Google OAuth 2.0 伺服器的回應,說明是否已授予任何存取權。詳細說明請參閱下列步驟。

錯誤

向 Google OAuth 2.0 授權端點發出的要求可能會顯示向使用者顯示的錯誤訊息,而非預期的驗證和授權流程。以下列出常見的錯誤代碼和建議解決方法。

admin_policy_enforced

Google 帳戶無法依據 Google Workspace 管理員的政策,授權給一或多個要求的範圍。請參閱 Google Workspace 管理員說明文章「 控管哪些第三方應用程式和內部應用程式可存取 Google Workspace 資料」,進一步瞭解管理員如何限制所有範圍或敏感/受限制範圍的存取權,直到明確授予 OAuth 用戶端 ID 存取權為止。

disallowed_useragent

授權端點顯示在嵌入式使用者代理程式中,而 Google 的 OAuth 2.0 政策不允許使用。

Android

Android 開發人員在 android.webkit.WebView 中開啟授權要求時,可能會看見這則錯誤訊息。開發人員應改用 Android 程式庫,例如 Android 版 Google 登入或 OpenID Foundation 的 AppAuth for Android

如果 Android 應用程式是在嵌入式使用者代理程式中開啟一般網頁連結,當使用者從您的網站前往 Google 的 OAuth 2.0 授權端點時,就可能會遇到這個錯誤。開發人員應允許在作業系統的預設連結處理常式中開啟一般連結,包括 Android 應用程式連結處理常式或預設瀏覽器應用程式。此外,您也可以使用「Android 自訂分頁」程式庫。

iOS

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

如果 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) 流程。請參閱遷移指南來更新整合作業。

invalid_request

您提出的要求出現錯誤。可能的原因包括:

  • 要求的格式不正確
  • 要求缺少必要參數
  • 該要求使用 Google 不支援的授權方法。確認 OAuth 整合作業使用建議的整合方法

步驟 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 參數以外,片段字串也包含一律設為 Bearertoken_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.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 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 的呼叫 (例如呼叫 YouTube Data API 時)。

請注意,YouTube Data API 僅支援擁有及管理多個 YouTube 頻道的 YouTube 內容擁有者 (例如唱片標籤和電影公司) 的服務帳戶。

您可以試用所有 Google API,並前往 OAuth 2.0 Playground 查看其範圍。

HTTP GET 範例

使用 Authorization: Bearer HTTP 標頭呼叫 youtube.channels 端點 (YouTube Data API) 可能如下所示。請注意,您必須指定自己的存取權杖:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

以下是使用 access_token 查詢字串參數對已驗證使用者的呼叫相同 API:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl 範例

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

JavaScript 程式碼範例

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

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

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/channels?part=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 的 channels.list 方法,擷取授權使用者的 YouTube 頻道相關資料。

  4. 如果要求成功執行,系統會將 API 回應記錄在瀏覽器的偵錯控制台中。

您可以透過 Google 帳戶的權限頁面撤銷應用程式的存取權。這個應用程式將列為 Google API 文件的 OAuth 2.0 示範

如要在本機執行這段程式碼,您必須為與授權憑證對應的 YOUR_CLIENT_IDYOUR_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/youtube/v3/channels?part=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() {
    // 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': '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 配置,而非純文字。本機主機 URI (包括 localhost IP 位址 URI) 不受這項規則影響。

主機

主機不得為原始 IP 位址。本機主機 IP 位址則不受這項規則影響。

網域
  • 主機 TLD (頂層網域) 必須屬於公開後置字串清單
  • 主機網域不得為 “googleusercontent.com”
  • 除非應用程式擁有網域,否則 JavaScript 來源不得包含網址縮短網域 (例如 goo.gl)。
  • 使用者資訊

    JavaScript 來源不得包含 userinfo 子元件。

    路徑

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

    查詢

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

    Fragment

    JavaScript 來源不得包含片段元件。

    字元 JavaScript 來源不得包含某些字元,包括:
    • 萬用字元 ('*')
    • 不可列印的 ASCII 字元
    • 百分比編碼無效 (任何未遵循網址編碼形式的百分比符號後面加上兩個十六進位數字)
    • 空值字元 (經過編碼的 NULL 字元,例如%00%C0%80)

    增量授權

    在 OAuth 2.0 通訊協定中,應用程式會要求存取資源的授權,而這些資源會依據範圍識別。對使用者體驗而言,最好在需要時要求資源授權,是最佳的使用者體驗。Google 的授權伺服器支援漸進式授權,因此您可以採取這項做法。這項功能可讓您視需要要求範圍,如果使用者授予新範圍的權限,系統會傳回授權碼來交換憑證,該代碼會包含使用者已授予專案的所有範圍。

    舉例來說,假設應用程式可協助使用者找出有趣的當地事件。應用程式可讓使用者觀看活動影片、為影片評分,並將影片新增至播放清單。使用者也可以透過應用程式將活動新增至自己的 Google 日曆。

    在此情況下,在應用程式登入時,應用程式可能不需要或要求任何範圍的存取權。不過,如果使用者嘗試為影片評分、將影片加入播放清單,或是執行其他 YouTube 動作,應用程式可能會要求 https://www.googleapis.com/auth/youtube.force-ssl 範圍的存取權。同樣地,如果使用者嘗試新增日曆活動,應用程式可以要求 https://www.googleapis.com/auth/calendar 範圍的存取權。

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

    • 此權杖可用於存取匯總至新的合併授權範圍內的任何範圍資源。
    • 當您使用更新權杖進行合併授權來取得存取權杖時,存取權杖代表合併的授權,並可用於回應中包含的任何 scope 值。
    • 合併的授權包括使用者授予 API 專案的所有範圍,即使授權是從不同的用戶端要求也是如此。舉例來說,如果使用者透過應用程式的桌面用戶端授予某個範圍的存取權,然後透過行動用戶端將另一個範圍授予同一個應用程式,則合併的授權將包含這兩個範圍。
    • 如果您撤銷代表合併授權的權杖,代表關聯使用者存取該授權的所有範圍都會同時撤銷。

    下列程式碼範例說明如何將範圍新增至現有的存取權杖。這種做法可讓應用程式省去管理多個存取權杖的麻煩。

    OAuth 2.0 端點

    在這個範例中,除了使用者已授予應用程式的其他存取權外,呼叫應用程式也會要求擷取使用者的 YouTube Analytics (分析) 資料。

    如要將範圍新增至現有的存取權杖,請在對 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.
    }

    撤銷權杖

    在某些情況下,使用者可能會想撤銷應用程式的存取權。使用者可以前往 帳戶設定撤銷存取權。詳情請參閱「在具有帳戶存取權的第三方網站和應用程式中移除網站或應用程式存取權」支援文件。

    應用程式也可以透過程式撤銷獲得的存取權。當使用者取消訂閱、移除應用程式,或應用程式所需的 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();
    }