網路驗證通訊協定使用 HTTP 功能,但 Chrome 應用程式是在應用程式容器中執行;無法透過 HTTP 載入,也無法執行重新導向或設定 Cookie。
使用 Chrome Identity API 驗證使用者:getAuthToken
適用於已登入 Google 帳戶的使用者,針對登入非 Google 帳戶的使用者使用 launchWebAuthFlow
。如果您的應用程式透過自己的伺服器驗證使用者,則需要使用後者。
運作方式
Chrome 應用程式使用者擁有與設定檔相關聯的 Google 帳戶。應用程式可以使用 getAuthToken
API 為這些使用者取得 OAuth2 權杖。
應用程式必須呼叫 launchWebAuthFlow
,才能使用非 Google 識別資訊提供者進行驗證。這個方法會使用瀏覽器彈出式視窗顯示供應者頁面,並擷取重新導向到特定網址模式。系統會將重新導向網址傳遞至應用程式,而應用程式會從網址中擷取符記。
Google 帳戶驗證
以下是需要完成的五個步驟:
- 在資訊清單中新增權限並上傳應用程式。
- 將已安裝
manifest.json
中的金鑰複製到來源資訊清單,讓應用程式 ID 在開發期間保持不變。 - 取得 Chrome 應用程式的 OAuth2 用戶端 ID。
- 更新資訊清單,加入用戶端 ID 和範圍。
- 取得驗證權杖。
新增權限並上傳應用程式
您必須確認資訊清單中的身分權限。然後再將應用程式上傳至應用程式和擴充功能管理頁面 (請參閱「發布」)。
"permissions": [
"identity"
]
將金鑰複製到資訊清單
在 Google OAuth 控制台中註冊應用程式時,您會提供應用程式 ID,系統會在憑證要求期間檢查這組 ID。因此,在開發期間,應用程式 ID 必須一致。
為了讓應用程式 ID 常數保持不變,您必須將已安裝 manifest.json
中的金鑰複製到來源資訊清單。這不是最舒適的任務,不過方法如下:
- 前往您的使用者資料目錄。macOS 範例:
~/Library/Application\ Support/Google/Chrome/Default/Extensions
- 列出已安裝的應用程式和擴充功能,然後在「應用程式和擴充功能管理」頁面上比對您的應用程式 ID,與這裡相同的 ID。
- 前往安裝版應用程式目錄 (這是應用程式 ID 中的版本)。開啟已安裝的
manifest.json
(使用 Pico 即可快速開啟檔案)。 - 複製已安裝
manifest.json
中的「金鑰」,並貼到應用程式的來源資訊清單檔案中。
取得 OAuth2 用戶端 ID
您必須在 Google API 控制台中註冊應用程式,以取得用戶端 ID:
- 以用來將應用程式上傳至 Chrome 線上應用程式商店的 Google 帳戶,登入 Google API 控制台。
- 展開左上角的下拉式選單,然後選取「Create...」選單項目,即可建立新專案。
- 建立並命名後,請前往「服務」導覽選單項目,然後開啟應用程式所需的任何 Google 服務。
- 前往「API Access」(API 存取權) 導覽選單項目,然後按一下「Create an OAuth 2.0 client ID...」(建立 OAuth 2.0 用戶端 ID...) 藍色按鈕。
- 請輸入必要的品牌資訊,選取「已安裝的應用程式」類型。
- 選取「Chrome Application」,然後輸入應用程式 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,如以下螢幕截圖所示:
如果您在無訊息模式叫用 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 帳戶驗證
您必須完成下列三個步驟:
- 向供應商註冊。
- 新增應用程式要存取的提供者資源權限。
- 取得驗證權杖。
向供應商註冊
您需要向供應商註冊 OAuth2 用戶端 ID,並將用戶端 ID 設為網站。請使用以下表單網址,在註冊期間輸入的重新導向 URI:
https://<extension-id>.chromiumapp.org/<anything-here>
舉例來說,如果應用程式 ID 是 abcdefghijklmnopqrstuvwxyzabcdef
,而您想要 provider_cb
是路徑,以便與重新導向 URI 與其他提供者區分,則應使用 https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb
:
新增提供者的權限
如要將跨來源 XHR 用於提供者 API 端點,您需要在權限中將適當模式加入許可清單:
"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)。
如果在無訊息模式下叫用 API,則只有在提供者能夠提供權杖而不顯示任何 UI 時,API 才會傳回權杖。舉例來說,當應用程式在應用程式啟動時執行流程時,這項功能非常實用,或者在一般情況下並未涉及使用者手勢。
我們建議的最佳做法,是在沒有使用者手勢的情況下使用靜音模式,並在使用者手勢 (例如使用者在應用程式中點選「登入」按鈕) 時使用互動模式。請注意,我們不會強制執行手勢要求。