將應用程式連線至驗證模擬器

在應用程式中使用 Authentication 模擬器前,請務必瞭解整體 Firebase Local Emulator Suite 工作流程,並安裝及設定 Local Emulator Suite,並查看其 CLI 指令

本主題假設您已熟悉如何開發用於實際工作環境的 Firebase Authentication 解決方案。如有需要,請參閱平台和驗證技術組合的說明文件。

Authentication 模擬器有什麼用途?

Authentication 模擬器可提供 Firebase Authentication 服務的高保真本機模擬功能,提供 實際工作環境 Firebase Authentication 中的大部分功能。搭配 Apple 平台、Android 和 Web Firebase SDK,模擬器可讓您:

  • 建立、更新及管理模擬使用者帳戶,以便測試電子郵件/密碼、電話號碼/簡訊、簡訊多重驗證機制,以及第三方 (例如 Google) 識別資訊提供者驗證
  • 查看及編輯模擬使用者
  • 自訂權杖驗證系統的原型
  • 在「Emulator UI Logs」分頁中查看驗證相關訊息。

選擇 Firebase 專案

Firebase Local Emulator Suite 會模擬單一 Firebase 專案的產品。

如要選取要使用的專案,請在啟動模擬器前,在工作目錄的 CLI 中執行 firebase use。或者,您也可以將 --project 標記傳遞至每個模擬器指令。

Local Emulator Suite 支援模擬實際 Firebase 專案和示範專案。

專案類型 功能 搭配模擬器使用
真實

真正的 Firebase 專案是您建立及設定的專案 (最有可能是透過 Firebase 控制台)。

實際專案會有即時資源,例如資料庫執行個體、儲存空間桶、函式,或您為該 Firebase 專案設定的任何其他資源。

使用實際的 Firebase 專案時,您可以為任何或所有支援的產品執行模擬器。

對於您未模擬的任何產品,應用程式和程式碼會與實際資源 (資料庫執行個體、儲存空間 bucket、函式等) 互動。

示範

示範 Firebase 專案沒有實際的 Firebase 設定,也沒有實際資源。這些專案通常是透過程式碼研究室或其他教學課程存取。

示範專案的專案 ID 會加上 demo- 前置字串。

使用 Firebase 示範專案時,應用程式和程式碼只會與模擬器互動。如果應用程式嘗試與模擬器未執行的資源互動,該程式碼就會失敗。

建議您盡可能使用示範專案。Meet 具備以下優點:

  • 設定更簡單,因為您可以不必建立 Firebase 專案,即可執行模擬器
  • 安全性更高,因為如果程式碼不小心叫用未模擬的 (實際) 資源,就不會發生資料變更、使用和帳單問題
  • 提供更完善的離線支援功能,因為您不需要連上網際網路即可下載 SDK 設定。

檢測應用程式以與模擬器通訊

Android、iOS 和網頁 SDK

如要設定應用程式內設定或測試類別,以便與 Authentication 模擬器互動,請按照下列步驟操作:

Kotlin+KTX
Firebase.auth.useEmulator("10.0.2.2", 9099)
Java
FirebaseAuth.getInstance().useEmulator("10.0.2.2", 9099);
Swift
Auth.auth().useEmulator(withHost:"127.0.0.1", port:9099)

Web

import { getAuth, connectAuthEmulator } from "firebase/auth";

const auth = getAuth();
connectAuthEmulator(auth, "http://127.0.0.1:9099");

Web

const auth = firebase.auth();
auth.useEmulator("http://127.0.0.1:9099");

您不需要額外設定,即可為 Cloud FirestoreRealtime Database 建立 AuthenticationCloud FunctionsFirebase Security Rules 之間的原型設計,並測試兩者之間的互動。設定 Authentication 模擬器並執行其他模擬器後,這些模擬器會自動搭配運作。

Admin SDK

設定 FIREBASE_AUTH_EMULATOR_HOST 環境變數後,Firebase Admin SDK 會自動連線至 Authentication 模擬器。

export FIREBASE_AUTH_EMULATOR_HOST="127.0.0.1:9099"

請注意,Cloud Functions 模擬器會自動偵測 Authentication 模擬器,因此您可以在測試 Cloud FunctionsAuthentication 模擬器之間的整合時略過這個步驟。系統會自動為 Cloud Functions 中的 Admin SDK 設定環境變數。

設定環境變數後,Firebase Admin SDK 會接受由 Authentication 模擬器 (分別透過 verifyIdTokencreateSessionCookie 方法) 發出的未簽署 ID 權杖和工作階段 Cookie,以利本機開發和測試。請務必在正式環境中設定環境變數。

如果您希望 Admin SDK 程式碼連線至在其他環境中執行的共用模擬器,則需要指定使用 Firebase CLI 設定的專案 ID。您可以直接將專案 ID 傳遞至 initializeApp,或設定 GCLOUD_PROJECT 環境變數。

Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
環境變數
export GCLOUD_PROJECT="your-project-id"

ID 權杖

基於安全考量,Authentication 模擬器會發出未簽署的 ID 權杖,這些權杖只會由其他 Firebase 模擬器或 Firebase Admin SDK (在設定後) 接受。這些權杖會遭到實際工作環境中的實際 Firebase 服務或 Firebase Admin SDK (例如未執行上述設定步驟的預設行為) 拒絕。

啟動模擬器

您可以透過 Emulator Suite UI 以互動方式使用 Authentication 模擬器,也可以透過本機 REST 介面以非互動方式使用。以下章節將說明互動和非互動用途。

如要啟動 Authentication 模擬器、其 REST 介面和 Emulator Suite UI,請執行以下命令:

firebase emulators:start

對於匿名驗證,您的應用程式可以執行平台 (iOSAndroid網頁) 的登入邏輯。

如要進行電子郵件/密碼驗證,您可以使用 Authentication SDK 方法,將使用者帳戶新增至應用程式的 Authentication 模擬器,或是使用 Emulator Suite UI 開始製作原型。

  1. Emulator Suite UI 中,按一下「Authentication」分頁標籤。
  2. 按一下「新增使用者」按鈕。
  3. 按照使用者帳戶建立精靈的步驟,填寫電子郵件驗證欄位。

建立測試使用者後,應用程式就能使用平台 (iOSAndroid網頁) 的 SDK 邏輯,讓使用者登入或登出。

如要測試透過電子郵件連結流程進行電子郵件驗證/登入,模擬器會將網址列印到執行 firebase emulators:start 的終端機。

i  To verify the email address customer@ex.com, follow this link:
http://127.0.0.1:9099/emulator/action?mode=verifyEmail&lang=en&oobCode=XYZ123&apiKey=fake-api-key

將連結貼到瀏覽器中模擬驗證事件,並檢查驗證是否成功。

{
  "authEmulator": {
    "success": "The email has been successfully verified.",
    "email": "customer@example.com"
  }
}

如要測試密碼重設功能,模擬器會在終端機上顯示類似的網址,包括 newPassword 參數 (可視需要變更)。

http://127.0.0.1:9099/emulator/action?mode=resetPassword&oobCode=XYZ!23&apiKey=fake-api-key&newPassword=YOUR_NEW_PASSWORD

非互動式測試

您可以編寫測試設定指令碼,呼叫 REST API 來建立及刪除使用者帳戶,並擷取非正式管道電子郵件驗證碼,填入模擬器電子郵件驗證網址,而非使用 Emulator Suite UI 或用戶端程式碼來管理電子郵件/密碼使用者帳戶。這樣一來,平台和測試程式碼就會保持分開,您也可以進行非互動式測試。

對於非互動式電子郵件和密碼測試流程,一般會依照下列順序進行。

  1. 使用 Authentication signUp REST 端點建立使用者。
  2. 使用者使用電子郵件地址和密碼登入,以便進行測試。
  3. 如果適用於您的測試,請從模擬器專屬 REST 端點擷取可用的額外電子郵件驗證碼。
  4. 使用模擬器專屬的 REST 端點清除資料,以便清除使用者記錄。

模擬電話/簡訊驗證

針對手機驗證,Auth 模擬器不支援以下項目:

  • reCAPTCHA 和 APN 流程。一旦設定為與模擬器互動,用戶端 SDK 會以與整合測試類似的方式停用這些驗證方法 (iOSAndroid網頁)。
  • Firebase 控制台中預先設定代碼,測試電話號碼。

否則,就用戶端程式碼而言,電話/簡訊驗證流程與說明的正式版流程相同 (iOSAndroid網頁)。

使用 Emulator Suite UI

  1. Emulator Suite UI 中,按一下「Authentication」分頁標籤。
  2. 按一下「新增使用者」按鈕。
  3. 按照使用者帳戶建立精靈的步驟,填寫電話驗證欄位。

不過,對於電話驗證流程,模擬器不會觸發任何簡訊的傳送,因為聯絡電信業者超出範圍,也不利於本機測試!相反地,模擬器會列印出透過簡訊傳送至您執行 firebase emulators:start 的相同終端機的程式碼;將此程式碼輸入應用程式,模擬使用者查看簡訊的情況。

非互動式測試

如要進行非互動式電話驗證測試,請使用 Authentication 模擬器 REST API 擷取可用的簡訊驗證碼。請注意,每次啟動流程時,程式碼都會有所不同。

一般流程如下:

  1. 呼叫平台 signInWithPhoneNumber 即可開始驗證程序。
  2. 使用模擬器專屬 REST 端點擷取驗證碼。
  3. 使用驗證碼照常撥打 confirmationResult.confirm(code)

簡訊多重驗證

Authentication 模擬器支援原型設計,並測試可在 iOSAndroid網頁正式版中使用的 SMS 多因素驗證 (MFA) 流程。

在模擬器中新增模擬使用者時,您可以啟用多重驗證,並設定一或多個要傳送次要驗證簡訊的電話號碼。訊息會輸出至您執行 firebase emulators:start 的相同終端機,並可透過 REST 介面存取。

模擬第三方識別資訊提供者 (IDP) 驗證

Authentication 模擬器可讓您在 iOS、Android 或網頁應用程式中測試許多第三方驗證流程,而無須變更實際運作中的程式碼。如需驗證流程的範例,請參閱說明文件,瞭解您可以在應用程式中使用的各種供應商和平台組合

一般來說,您可以使用 Firebase SDK 透過下列兩種方式進行驗證:

  • 您的應用程式會讓 SDK 處理整個端對端程序,包括與第三方 IDP 供應器的所有互動,以便擷取憑證。
  • 您的應用程式會使用第三方供應商的 SDK 手動擷取該供應商的憑證,並將這些憑證傳遞至 Authentication SDK。

再次提醒您,請查看上述說明文件連結,並確認您熟悉要使用的流程 (Firebase SDK 管理的流程或手動憑證擷取流程)。Authentication 模擬器支援這兩種測試方法。

測試 Firebase SDK 驅動的 IDP 流程

如果您的應用程式使用任何 Firebase SDK 端對端流程,例如 OAuthProvider 以便透過 Microsoft、GitHub 或 Yahoo 登入,以便進行互動式測試,Authentication 模擬器會提供對應登入頁面的本機版本,協助您測試呼叫 signinWithPopupsignInWithRedirect 方法的網頁應用程式驗證機制。這個本機提供的登入頁面也會顯示在行動應用程式中,由平台的 WebView 程式庫算繪。

模擬器會在流程進行時,視需要建立模擬第三方使用者帳戶和憑證。

透過手動憑證擷取功能測試 IdP 流程

如果您使用「手動」登入技巧,並呼叫平台的 signInWithCredentials 方法,則應用程式會照常要求實際的第三方登入,並擷取實際的第三方憑證。

請注意,模擬器只支援 signInWithCredential 驗證,適用於從 Google 登入、Apple 和其他使用 ID 權杖 (以 JSON Web Token (JWT) 實作) 的提供者擷取的憑證。不支援存取權杖 (例如 Facebook 或 Twitter 提供的非 JWT 權杖)。下一節將討論這些情況的替代做法。

非互動式測試

非互動式測試的一種方法,就是自動模擬使用者在模擬器提供的登入頁面上點按。如果是網頁應用程式,請使用 WebDriver 等控制介面。如果是行動裝置,請使用平台的 UI 測試工具,例如 Espresso 或 Xcode。

或者,您可以更新程式碼,以便使用 signInWithCredential (例如在程式碼分支中),並使用權杖驗證流程,為帳戶提供模擬 ID 權杖,而非實際憑證。

  1. 重新連線或註解掉從 IDP 擷取 idToken 的程式碼部分,這樣就不必在測試期間輸入實際的使用者名稱和密碼,而且測試不會受到 IDP 的 API 配額和速率限制影響。
  2. 第二,請使用 JSON 字串常值取代 signInWithCredential 的符記。以網頁 SDK 為例,您可以將程式碼變更為:
firebase.auth().signInWithCredential(firebase.auth.GoogleAuthProvider.credential(
  '{"sub": "abc123", "email": "foo@example.com", "email_verified": true}'
));

搭配模擬器使用時,這個程式碼會成功驗證使用者在 Google 的電子郵件地址 foo@example.com。請將子欄位視為主鍵,可變更為任何字串,模擬登入不同使用者的情況。您可以將 firebase.auth.GoogleAuthProvider 替換為 new firebase.auth.OAuthProvider('yahoo.com') 或您要模擬的任何其他供應器 ID。

模擬自訂權杖驗證

Authentication 模擬器會在支援的平台上使用對 signInWithCustomToken 方法的呼叫,以自訂 JSON Web Token 處理驗證作業,如正式版 Authentication 說明文件所述。

Authentication 模擬器與實際環境的差異

Firebase Authentication 模擬器可模擬實際產品的許多功能。不過,由於任何類型的驗證系統都極度依賴多層級 (裝置、第三方供應商、Firebase 等) 的安全性,因此模擬器很難正確重建所有流程。

Cloud IAM

Firebase 模擬器套件不會嘗試複製或遵循任何與 IAM 相關的執行行為。模擬器會遵循提供的 Firebase 安全性規則,但在通常會使用 IAM 的情況下 (例如設定 Cloud Functions 叫用服務帳戶和相關權限),模擬器無法設定,並會在開發人員電腦上使用全域可用的帳戶,類似於直接執行本機指令碼。

由於在行動平台上,電子郵件連結登入功能會依賴 Firebase Dynamic Links,因此所有這類連結都會改為在 (行動) 網頁平台上開啟。

第三方登入

針對第三方登入流程,Firebase Authentication 會使用 Twitter 和 GitHub 等第三方供應商提供的安全憑證。

Authentication 模擬器會接受 Google 和 Apple 等 OpenID Connect 供應商提供的實際憑證。系統不支援非 OpenID Connect 提供者的憑證。

電子郵件 / 簡訊登入

在實際應用程式中,電子郵件和簡訊登入流程會涉及非同步作業,使用者會檢查收到的訊息,並在登入介面中輸入登入代碼。Authentication 模擬器不會傳送任何電子郵件或簡訊,但如上文所述,它會產生登入代碼,並將這些代碼輸出至測試用終端機。

模擬器不支援使用固定登入碼定義測試電話號碼的功能,但您可以使用 Firebase 主控台執行這項操作。

自訂權杖驗證

Authentication 模擬器不會驗證自訂權杖的簽名或到期日。這樣一來,您就能在原型設計和測試情境中使用手動建立的符記,並無限期重複使用符記。

頻率限制 / 反濫用

Authentication 模擬器不會複製實際的頻率限制或反濫用功能。

封鎖函式

在實際環境中,系統會在觸發 beforeCreatebeforeSignIn 事件後,將使用者寫入儲存空間一次。不過,由於技術限制,Authentication 模擬器會寫入儲存空間兩次,一次是在建立使用者後,另一次是在登入後。也就是說,對於新使用者而言,您可以在 Authentication 模擬器中成功呼叫 beforeSignIn 中的 getAuth().getUser(),但在實際環境中執行此操作時會發生錯誤。

後續步驟