在將身份驗證模擬器與您的應用程序一起使用之前,請確保您了解整個 Firebase Local Emulator Suite 工作流程,並安裝和配置Local Emulator Suite 並查看其CLI 命令。
本主題假設您已經熟悉為生產環境開發 Firebase 身份驗證解決方案。如果需要,請查看您的平台和身份驗證技術組合的文檔。
我可以使用身份驗證模擬器做什麼?
身份驗證模擬器提供 Firebase 身份驗證服務的高保真本地模擬,提供生產 Firebase 身份驗證中的大部分功能。與 Apple 平台、Android 和 Web Firebase SDK 配對後,該模擬器可以讓您:
- 創建、更新和管理模擬用戶帳戶,用於測試電子郵件/密碼、電話號碼/SMS、SMS 多因素和第三方(例如 Google)身份提供者身份驗證
- 查看和編輯模擬用戶
- 原型定制令牌認證系統
- 在模擬器 UI 日誌選項卡中檢查與身份驗證相關的消息。
選擇一個 Firebase 項目
Firebase Local Emulator Suite 模擬單個 Firebase 項目的產品。
要選擇要使用的項目,請在啟動模擬器之前,在 CLI 中運行firebase use
。或者,您可以將--project
標誌傳遞給每個模擬器命令。
Local Emulator Suite 支持模擬真實的Firebase 項目和演示項目。
項目類型 | 特徵 | 與模擬器一起使用 |
---|---|---|
真實的 | 一個真正的 Firebase 項目是您創建和配置的項目(很可能是通過 Firebase 控制台)。 真實項目具有實時資源,例如數據庫實例、存儲桶、函數或您為該 Firebase 項目設置的任何其他資源。 | 在處理真實的 Firebase 項目時,您可以為任何或所有受支持的產品運行模擬器。 對於您未模擬的任何產品,您的應用程序和代碼將與實時資源(數據庫實例、存儲桶、函數等)交互。 |
演示 | 一個演示 Firebase 項目沒有真正的Firebase 配置,也沒有實時資源。這些項目通常通過代碼實驗室或其他教程訪問。 演示項目的項目 ID 具有 | 使用演示 Firebase 項目時,您的應用程序和代碼僅與模擬器交互。如果您的應用程序嘗試與未運行模擬器的資源進行交互,則該代碼將失敗。 |
我們建議您盡可能使用演示項目。好處包括:
- 設置更簡單,因為您無需創建 Firebase 項目即可運行模擬器
- 更強的安全性,因為如果您的代碼不小心調用了非模擬(生產)資源,就沒有數據更改、使用和計費的機會
- 更好的離線支持,因為無需訪問互聯網即可下載您的 SDK 配置。
檢測您的應用以與模擬器對話
Android、iOS 和網絡 SDK
設置您的應用內配置或測試類以與身份驗證模擬器交互,如下所示。
Kotlin+KTX
Firebase.auth.useEmulator("10.0.2.2", 9099)
Java
FirebaseAuth.getInstance().useEmulator("10.0.2.2", 9099);
迅速
Auth.auth().useEmulator(withHost:"localhost", port:9099)
Web modular API
import { getAuth, connectAuthEmulator } from "firebase/auth"; const auth = getAuth(); connectAuthEmulator(auth, "http://localhost:9099");
Web namespaced API
const auth = firebase.auth(); auth.useEmulator("http://localhost:9099");
無需額外設置即可對身份驗證與 Cloud Functions 或 Cloud Firestore 或實時數據庫的 Firebase 安全規則之間的交互進行原型設計和測試。當配置了身份驗證模擬器並且其他模擬器正在運行時,它們會自動協同工作。
管理員 SDK
設置FIREBASE_AUTH_EMULATOR_HOST
環境變量後,Firebase Admin SDK 會自動連接到身份驗證模擬器。
export FIREBASE_AUTH_EMULATOR_HOST="localhost:9099"
請注意,Cloud Functions 模擬器會自動識別身份驗證模擬器,因此您可以在測試 Cloud Functions 和身份驗證模擬器之間的集成時跳過此步驟。將為 Cloud Functions 中的 Admin SDK 自動設置環境變量。
設置環境變量後,Firebase Admin SDK 將接受身份驗證模擬器發出的未簽名 ID 令牌和會話 cookie(分別通過verifyIdToken
和createSessionCookie
方法)以促進本地開發和測試。請確保不要在生產環境中設置環境變量。
如果您希望您的 Admin SDK 代碼連接到在另一個環境中運行的共享模擬器,您將需要指定您使用 Firebase CLI 設置的相同項目 ID 。您可以將項目 ID 直接傳遞給initializeApp
或設置GCLOUD_PROJECT
環境變量。
Node.js 管理 SDK
admin.initializeApp({ projectId: "your-project-id" });
環境變量
export GCLOUD_PROJECT="your-project-id"
身份證
出於安全原因,身份驗證模擬器會發出未簽名的ID 令牌,只有其他 Firebase 模擬器或 Firebase Admin SDK 在配置時才接受這些令牌。這些令牌將被在生產模式下運行的生產 Firebase 服務或 Firebase Admin SDK 拒絕(例如,沒有上述設置步驟的默認行為)。
啟動模擬器
您可以通過 Emulator Suite UI 以交互方式使用身份驗證模擬器,也可以通過其本地 REST 界面以非交互方式使用身份驗證模擬器。以下部分涵蓋交互式和非交互式用例。
要啟動 Authentication 模擬器、它的 REST 接口和 Emulator Suite UI,請執行:
firebase emulators:start
模擬電子郵件、電子郵件鏈接和匿名身份驗證
對於匿名身份驗證,您的應用程序可以為您的平台( iOS 、 Android 、 Web )執行登錄邏輯。
對於電子郵件/密碼身份驗證,您可以通過使用身份驗證 SDK 方法或使用模擬器套件 UI 從您的應用程序將用戶帳戶添加到身份驗證模擬器來開始原型設計。
- 在 Emulator Suite UI 中,單擊身份驗證選項卡。
- 單擊添加用戶按鈕。
- 按照用戶帳戶創建嚮導,填寫電子郵件身份驗證字段。
創建測試用戶後,您的應用程序可以使用適用於您的平台( iOS 、 Android 、 Web )的 SDK 邏輯讓用戶登錄和註銷。
為了使用電子郵件鏈接流測試電子郵件驗證/登錄,模擬器將 URL 打印到執行firebase emulators:start
的終端。
i To verify the email address customer@ex.com, follow this link:
http://localhost: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"
}
}
為了測試密碼重置,模擬器會向終端打印一個類似的 URL,其中包括一個newPassword參數(您可以根據需要更改該參數)。
http://localhost:9099/emulator/action?mode=resetPassword&oobCode=XYZ!23&apiKey=fake-api-key&newPassword=YOUR_NEW_PASSWORD
非交互式測試
您可以編寫測試設置腳本來調用 REST API 來創建和刪除用戶帳戶,並獲取帶外電子郵件驗證代碼以填充模擬器電子郵件驗證,而不是使用 Emulator Suite UI 或客戶端代碼來管理電子郵件/密碼用戶帳戶網址。這使平台和測試代碼保持分離,並允許您進行非交互式測試。
對於非交互式電子郵件和密碼測試流程,典型順序如下。
- 使用 Authentication signUp REST 端點創建用戶。
- 使用電子郵件和密碼登錄用戶以執行測試。
- 如果適用於您的測試,請從特定於模擬器的 REST 端點獲取可用的帶外電子郵件驗證碼。
- 使用特定於模擬器的 REST 端點刷新用戶記錄以清除數據。
模擬電話/短信認證
對於手機身份驗證,Auth 模擬器不支持:
- reCAPTCHA 和 APN 流。一旦配置為與模擬器交互,客戶端 SDK 就會以類似於集成測試( iOS 、 Android 、 Web )所描述的方式禁用這些驗證方法。
- 使用 Firebase 控制台中預配置的代碼測試電話號碼。
否則,就客戶端代碼而言,電話/SMS 身份驗證流程與生產環境( iOS 、 Android 、 Web )中描述的相同。
使用模擬器套件用戶界面:
- 在 Emulator Suite UI 中,單擊身份驗證選項卡。
- 單擊添加用戶按鈕。
- 按照用戶帳戶創建嚮導,填寫電話驗證字段。
但是,對於電話身份驗證流程,模擬器不會觸發任何文本消息的傳遞,因為聯繫運營商超出範圍並且不利於本地測試!相反,模擬器會打印出本應通過 SMS 發送到您運行firebase emulators:start
的同一終端的代碼;將此代碼輸入應用程序以模擬用戶檢查他們的短信。
非交互式測試
對於非交互式電話身份驗證測試,請使用身份驗證模擬器 REST API 檢索可用的 SMS 代碼。請注意,每次啟動流程時代碼都不同。
典型的順序如下。
- 調用平台
signInWithPhoneNumber
啟動驗證過程。 - 使用特定於模擬器的 REST 端點檢索驗證碼。
- 像往常一樣用驗證碼調用
confirmationResult.confirm(code)
。
多因素短信
身份驗證模擬器支持原型設計和測試在iOS 、 Android和web的生產中可用的 SMS 多因素身份驗證 (MFA) 流。
當您將模擬用戶添加到模擬器時,您可以啟用 MFA 並配置一個或多個電話號碼,第二因素 SMS 消息將發送到這些電話號碼。消息輸出到您運行firebase emulators:start
的同一終端,並可從 REST 界面訪問。
模擬第三方身份提供者 (IDP) 身份驗證
身份驗證模擬器可讓您在 iOS、Android 或 Web 應用程序中測試許多第三方身份驗證流程,而無需更改生產代碼。有關身份驗證流程的示例,請參閱有關可在您的應用程序中使用的提供程序和平台的各種組合的文檔。
一般來說,您可以使用 Firebase SDK 通過以下兩種方式之一進行身份驗證:
- 您的應用程序讓 SDK 處理端到端的整個過程,包括與第三方 IDP 提供商的所有交互以檢索憑據。
- 您的應用程序使用第三方的 SDK 從第三方提供商手動檢索憑據,並將這些憑據傳遞給 Authentication SDK。
再次檢查上面的文檔鏈接,確保您熟悉您要使用的任何流程——Firebase SDK 管理的憑證檢索與手動憑證檢索。身份驗證仿真器支持測試任一方法。
測試 Firebase SDK 驅動的 IDP 流
如果您的應用程序使用任何 Firebase SDK 端到端流程(例如用於登錄 Microsoft、GitHub 或 Yahoo 的OAuthProvider
)進行交互式測試,則身份驗證模擬器會提供相應登錄頁面的本地版本來幫助您進行測試來自調用signinWithPopup
或signInWithRedirect
方法的 Web 應用程序的身份驗證。這個本地服務的登錄頁面也出現在移動應用程序中,由您平台的 webview 庫呈現。
隨著流程的進行,模擬器會根據需要創建模擬的第三方用戶帳戶和憑據。
使用手動憑證檢索測試 IDP 流程
如果您使用“手動”登錄技術並調用平台的signInWithCredentials
方法,那麼您的應用程序將像往常一樣請求真實的第三方登錄並檢索真實的第三方憑據。
請注意,模擬器僅支持對從 Google 登錄、Apple 和其他使用作為 JSON Web 令牌 (JWT) 實現的 ID 令牌的提供商檢索的憑據進行signInWithCredential
身份驗證。不支持訪問令牌(例如 Facebook 或 Twitter 提供的那些,它們不是 JWT)。下一節將討論這些情況下的替代方案。
非交互式測試
非交互式測試的一種方法是自動執行用戶在模擬器提供的登錄頁面上的點擊。對於網絡應用程序,請使用像 WebDriver 這樣的控制界面。對於移動設備,使用您平台上的 UI 測試工具,例如 Espresso 或 Xcode。
或者,您可以更新您的代碼以使用signInWithCredential
(例如,在代碼分支中)並使用帶有模擬 ID 令牌的令牌身份驗證流程來代替真實憑據。
- 重新連接或註釋掉從 IDP 檢索 idTokens 的代碼部分;這消除了在測試期間輸入真實用戶名和密碼的需要,並使您的測試免受 IDP 的 API 配額和速率限制。
- 其次,使用文字 JSON 字符串代替
signInWithCredential
的令牌。以web SDK為例,可以將代碼改成:
firebase.auth().signInWithCredential(firebase.auth.GoogleAuthProvider.credential(
'{"sub": "abc123", "email": "foo@example.com", "email_verified": true}'
));
當與模擬器一起使用時,此代碼將成功驗證電子郵件為foo@example.com
在 Google 的用戶。將子字段視為主鍵,可以更改為任何字符串,模擬不同用戶的簽名。例如,您可以將firebase.auth.GoogleAuthProvider
替換為new firebase.auth.OAuthProvider('yahoo.com')
或您想要模擬的任何其他提供商 ID。
模擬自定義令牌身份驗證
身份驗證模擬器通過在支持的平台上調用signInWithCustomToken
方法來處理自定義 JSON Web 令牌的身份驗證,如生產身份驗證文檔中所述。
身份驗證模擬器與生產環境有何不同
Firebase 身份驗證模擬器模擬生產產品的許多功能。但是,由於任何類型的身份驗證系統都嚴重依賴多個級別(設備、第 3 方提供商、Firebase 等)的安全性,因此模擬器很難正確地重新創建所有流程。
雲 IAM
Firebase 模擬器套件不會嘗試複製或遵守任何與 IAM 相關的運行行為。模擬器遵守提供的 Firebase 安全規則,但在通常使用 IAM 的情況下,例如設置 Cloud Functions 調用服務帳戶和權限,模擬器不可配置,將使用開發人員計算機上的全局可用帳戶,類似於直接運行本地腳本。
通過移動設備上的電子郵件鏈接登錄
由於在移動平台上,電子郵件鏈接登錄依賴於 Firebase 動態鏈接,所有此類鏈接將在(移動)網絡平台上打開。
第三方登錄
對於第三方登錄流程,Firebase 身份驗證依賴於來自 Twitter 和 Github 等第三方提供商的安全憑證。
身份驗證模擬器接受來自 OpenID Connect 提供商(例如 Google 和 Apple)的真實憑據。不支持來自非 OpenID Connect 提供商的憑據。
電子郵件/短信登錄
在生產應用程序中,電子郵件和 SMS 登錄流程涉及異步操作,在該操作中,用戶檢查收到的消息並將登錄代碼輸入登錄界面。身份驗證模擬器不發送任何電子郵件或 SMS 消息,但如上所述,它會生成登錄代碼並將它們輸出到終端以用於測試。
模擬器不支持使用固定登錄代碼定義測試電話號碼的功能,這可以使用 Firebase 控制台完成。
自定義令牌認證
身份驗證模擬器不會驗證自定義令牌的簽名或過期時間。這允許您在原型設計和測試場景中使用手工製作的令牌並無限期地重複使用令牌。
速率限制/反濫用
身份驗證模擬器不會復制生產速率限製或反濫用功能。
阻塞函數
在生產中,在beforeCreate
和beforeSignIn
事件都被觸發後,用戶被寫入存儲一次。但是,由於技術限制,身份驗證模擬器寫入存儲兩次,一次是在用戶創建之後,另一次是在登錄之後。這意味著對於新用戶,您可以在 Authentication 模擬器的beforeSignIn
中成功調用getAuth().getUser()
,但在生產環境中這樣做會遇到錯誤。
接下來是什麼?
如需一組精選視頻和詳細的操作示例,請關注Firebase 仿真器培訓播放列表。
由於觸發函數是與身份驗證的典型集成,因此請在本地運行函數中了解有關 Firebase 模擬器的 Cloud Functions 的更多信息。