使用者驗證

網路驗證通訊協定使用 HTTP 功能，但 Chrome 應用程式是在應用程式容器中執行，不會透過 HTTP 載入，也無法執行重新導向或設定 Cookie。

使用 Chrome Identity API 驗證使用者：如果使用者已登入 Google 帳戶，則使用 getAuthToken；如果使用者已登入非 Google 帳戶，則使用 launchWebAuthFlow。如果應用程式使用自有伺服器驗證使用者，就必須使用後者。

運作方式

Chrome 應用程式使用者會將 Google 帳戶與個人資料建立關聯。應用程式可以使用 getAuthToken API 為這些使用者取得 OAuth2 權杖。

如果想要透過非 Google 識別資訊提供者執行驗證，應用程式必須呼叫 launchWebAuthFlow。這個方法會使用瀏覽器彈出式視窗顯示供應商網頁，並擷取導向至特定網址模式的重新導向。重新導向網址會傳遞至應用程式，而應用程式會從網址中擷取權杖。

Google 帳戶驗證

請完成以下五個步驟：

  1. 在資訊清單中新增權限，然後上傳應用程式。
  2. 將已安裝 manifest.json 中的金鑰複製到來源資訊清單，這樣應用程式 ID 在開發期間就會保持不變。
  3. 取得 Chrome 應用程式的 OAuth2 用戶端 ID。
  4. 更新資訊清單，納入用戶端 ID 和範圍。
  5. 取得驗證權杖。

新增權限並上傳應用程式

您必須確認資訊清單包含身分權限。然後，再將應用程式上傳到應用程式和擴充功能管理頁面 (請參閱「發布」)。

"permissions": [
  "identity"
]

將金鑰複製到資訊清單

在 Google OAuth 主控台註冊應用程式時，您會提供應用程式 ID，系統會在權杖要求期間檢查該 ID。因此，在開發期間使用一致的應用程式 ID 非常重要。

為確保應用程式 ID 保持不變，您必須將已安裝 manifest.json 中的金鑰複製到來源資訊清單。這不是最優雅的做法，但以下是執行方式：

  1. 前往使用者資料目錄。在 Mac OS 上的範例： ~/Library/Application\ Support/Google/Chrome/Default/Extensions
  2. 列出已安裝的應用程式和擴充功能，並將應用程式和擴充功能管理頁面上的應用程式 ID 與此處的 ID 比對。
  3. 前往已安裝的應用程式目錄 (也就是應用程式 ID 中的版本)。開啟已安裝的 manifest.json (pico 是開啟檔案的快速方法)。
  4. 複製已安裝 manifest.json 中的「key」，然後貼到應用程式的原始資訊清單檔案中。

取得 OAuth2 用戶端 ID

您必須在 Google API 控制台中註冊應用程式，才能取得用戶端 ID：

  1. 使用上傳應用程式至 Chrome 網路商店時所用的 Google 帳戶登入 Google API 控制台。
  2. 展開左上角的下拉式選單，然後選取「Create...」選單項目，即可建立新專案。
  3. 建立並命名後，請前往「服務」導覽選單項目，並開啟應用程式所需的任何 Google 服務。
  4. 前往「API 存取權」導覽選單項目，然後按一下「建立 OAuth 2.0 用戶端 ID...」藍色按鈕。
  5. 輸入必要的品牌資訊，然後選取「已安裝應用程式」類型。
  6. 選取「Chrome 應用程式」，然後輸入應用程式 ID (與應用程式和擴充功能管理頁面中顯示的 ID 相同)。

使用 OAuth2 用戶端 ID 和範圍更新資訊清單

您需要更新資訊清單，加入用戶端 ID 和範圍。以下是 gdrive 範例的「oauth2」範例：

"oauth2": {
    "client_id": "665859454684.apps.googleusercontent.com",
    "scopes": [
      "https://www.googleapis.com/auth/drive"
    ]
  }

取得存取權杖

您現在可以呼叫 identity.getAuthToken 取得授權權杖。

chrome.identity.getAuthToken({ 'interactive': true }, function(token) {
  // Use the token.
});

使用者互動

呼叫 getAuthToken 時，您可以傳遞標記 (上例中的 'interactive': true)，指出要以互動模式還是靜默模式呼叫 API。如果您在互動模式中叫用 API，系統會在必要時向使用者顯示登入和/或核准 UI，如以下螢幕截圖所示：

螢幕截圖：顯示應用程式使用 Identity API 驗證 Google 帳戶時的 UI

如果您在靜默模式中叫用 API，API 只會在可在不顯示任何 UI 的情況下產生一個權杖時，才會傳回權杖。這在應用程式在啟動時執行流程的情況下很實用，例如在沒有使用者手勢的情況下。

我們建議的最佳做法是，在沒有使用者手勢的情況下使用靜默模式，在有使用者手勢的情況下使用互動模式 (例如，使用者按下應用程式中的「登入」按鈕)。請注意，我們不會強制規定任何手勢。

快取

Chrome 會在記憶體中快取存取權杖，因此您在需要使用權杖時，隨時可以呼叫 getAuthToken。快取會自動處理權杖到期問題。

您可以在 chrome://identity-internals 上查看目前的符記快取狀態。

在某些情況下 (例如使用者變更密碼)，未過期的存取權權杖就會停止運作。使用權杖的 API 呼叫會開始傳回 HTTP 狀態碼 401。如果您發現這種情況，可以呼叫 identity.removeCachedAuthToken，從 Chrome 快取中移除無效的權杖。

removeCachedAuthToken 使用範例：

// callback = function (error, httpStatus, responseText);
function authenticatedXhr(method, url, callback) {
  var retry = true;
  function getTokenAndXhr() {
    chrome.identity.getAuthToken({/* details */},
                                 function (access_token) {
      if (chrome.runtime.lastError) {
        callback(chrome.runtime.lastError);
        return;
      }

      var xhr = new XMLHttpRequest();
      xhr.open(method, url);
      xhr.setRequestHeader('Authorization',
                           'Bearer ' + access_token);

      xhr.onload = function () {
        if (this.status === 401 && retry) {
          // This status may indicate that the cached
          // access token was invalid. Retry once with
          // a fresh token.
          retry = false;
          chrome.identity.removeCachedAuthToken(
              { 'token': access_token },
              getTokenAndXhr);
          return;
        }

        callback(null, this.status, this.responseText);
      }
    });
  }
}

非 Google 帳戶驗證

您需要完成以下三個步驟：

  1. 向供應商註冊。
  2. 為應用程式要存取的供應器資源新增權限。
  3. 取得驗證權杖。

向供應商註冊

您必須向供應商註冊 OAuth2 用戶端 ID，並將用戶端 ID 設為網站。 如要輸入註冊期間的重新導向 URI，請使用下列格式的網址： https://<extension-id>.chromiumapp.org/<anything-here>

舉例來說，如果應用程式 ID 為 abcdefghijklmnopqrstuvwxyzabcdef，且您希望 provider_cb 是路徑，以便透過重新導向 URI 與其他供應商區隔，則應使用：https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb

新增提供者的權限

如要向供應商 API 端點發出跨來源 XHR，您必須在權限中加入適當的許可清單：

"permissions": [
  ...
  "https://www.website-of-provider-with-user-photos.com/photos/*"
]

取得權杖

如何取得權杖：

chrome.identity.launchWebAuthFlow(
  {'url': '<url-to-do-auth>', 'interactive': true},
  function(redirect_url) { /* Extract token from redirect_url */ });

<url-to-do-auth> 是要向供應商進行網站驗證的任何網址。舉例來說，假設您透過供應商執行 OAuth2 流程，並以用戶端 ID 123456789012345 註冊應用程式，而您想要存取供應商網站上的使用者相片： https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_id=123456789012345& redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb&response_type=token&scope=user_photos

供應商會執行驗證，並視需要向使用者顯示登入和/或核准 UI。然後重新導向至 https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token>

Chrome 會擷取該值，並使用完整的重新導向網址叫用應用程式的回呼。應用程式應從網址中擷取權杖。

互動模式與靜音模式

呼叫 launchWebAuthFlow 時，您可以傳遞旗標 (上述範例中的 'interactive': true)，指明是否要在互動模式中呼叫 API (又稱靜音模式)。如果您在互動模式中叫用 API，系統會視需要向使用者顯示 UI，以便取得符記 (登入 UI 和/或核准 UI；或任何提供者專屬的 UI)。

如果您以靜默模式叫用 API，只有在提供者能夠在不顯示任何 UI 的情況下提供權杖時，API 才會傳回權杖。這在應用程式在啟動時執行流程的情況下很實用，例如在沒有使用者手勢的情況下。

我們建議的最佳做法是，如果沒有使用者手勢，請使用靜音模式，如果有使用者手勢 (例如，使用者在應用程式中點選「登入」按鈕)，則請使用互動模式。請注意，我們不會強制執行手勢要求。