密碼金鑰簡介

網路功能： 網路驗證

本指南提供高密度、以行動為導向的指南，說明如何在現代網頁應用程式中，實作安全、與框架無關的密碼金鑰驗證和 Credential Manager。

1. 密碼金鑰的核心必要條件

密碼金鑰仰賴 Web Authentication API (WebAuthn)，該 API 會強制執行嚴格的跨領域安全性限制，在嘗試任何實作前，必須先滿足這些限制：

  • 安全環境：WebAuthn 方法 (navigator.credentials.create 和 navigator.credentials.get) 只能在安全環境中使用。應用程式必須在實際工作環境中透過 https:// 執行，或在本機開發環境中透過 http://localhost 執行。
  • 仰賴方 (RP) ID：每個憑證都會繫結至 RP ID (基本上是應用程式的網域名稱)。伺服器端選項中傳遞的 RP 身分憑證必須與目前來源的網域名稱相符，或是有效的後置字串 (例如 example.com 是 login.example.com 的有效後置字串)。如果不相符，用戶端會發生 SecurityError 例外狀況。

2. AAGUID 使用者體驗注意事項

驗證器認證全域專屬 ID (AAGUID) 是註冊認證資料中傳回的 128 位元 ID，代表驗證器的模型/供應商 (例如 Google 密碼管理工具、iCloud 鑰匙圈、1Password)。

  • 僅限使用者體驗提示：依賴方必須僅將 AAGUID 用於使用者體驗提示 (例如在管理清單中顯示密碼金鑰提供者名稱和圖示，協助使用者)。
  • 不依賴 AAGUID 確保安全：應用程式不得使用 AAGUID 進行加密編譯安全或存取決策。平台密碼金鑰目前不會為 AAGUID 提供密碼編譯認證，也就是說，使用者代理程式可以修改或模擬 AAGUID。

3. 分離式程式庫建議

如要產生後端 FIDO2/WebAuthn 選項和驗證簽章，開發人員必須依語言使用經過審查的開放原始碼程式庫，而非手動編寫密碼編譯：

  • JavaScript/TypeScript：SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
  • Python：py_webauthn (github.com/duo-labs/py_webauthn)
  • Java：Java WebAuthn Server (github.com/Yubico/java-webauthn-server)、WebAuthn4J (github.com/webauthn4j/webauthn4j)
  • .NET：FIDO2 的 .NET 程式庫 (github.com/abergs/fido2-net-lib)
  • Go：WebAuthn Go 程式庫 (github.com/go-webauthn/webauthn)
  • Ruby：WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
  • PHP：WebAuthn Framework (github.com/web-auth/webauthn-framework)

4. 用途參考矩陣

請找出符合您需求的用途，並取得完整的導入指南。每個用途都有重要的 API (PublicKeyCredential.parseCreationOptionsFromJSON、parseRequestOptionsFromJSON、signalAllAcceptedCredentials、signalCurrentUserDetails、signalUnknownCredential、條件式中介服務、AAGUID 處理等)，這些 API 僅在各用途指南中說明。請勿略過這個擷取步驟，也不要在用戶端替換第三方程式庫包裝函式 (例如 SimpleWebAuthn 的 startAuthentication/startRegistration)，而是直接呼叫原生 WebAuthn 瀏覽器 API。第 3 節的程式庫建議僅適用於伺服器端 (後端 FIDO2 驗證)。

特定密碼金鑰和 WebAuthn 導入詳細資料會對應至下列指南：