為 Android 應用程式選擇合適的密碼金鑰實作方式

密碼金鑰已成為安全、容易使用的驗證標準,越來越多服務在網站和 Android 應用程式中採用這項技術。不過,開始在 Android 應用程式中新增密碼金鑰時,您通常會面臨一個關鍵的架構問題:您要直接呼叫原生 API、在瀏覽器分頁中開啟現有的網頁登入頁面,還是在應用程式內 WebView 中執行密碼金鑰?

總覽

您可以透過三種主要方法,在 Android 應用程式中支援密碼金鑰:Credential Manager、Auth Tab 和 WebView。官方說明文件涵蓋各選項的逐步導入細節。如要選擇能盡量減少使用者摩擦,同時將開發和維護成本控制在可管理範圍內的架構,就必須大致瞭解每個選項的特性和限制。本指南說明如何根據應用程式的設計和現有驗證基礎架構,選擇合適的方法。下表比較了這些方法:

功能 Credential Manager 「驗證」分頁 WebView
建議用途 具有原生登入 UI 的應用程式 重複使用現有的網頁登入頁面,或 OAuth 或 OpenID Connect (OIDC) 識別資訊提供者 (IdP) 現有的混合式 WebView 應用程式 (僅限第一方網域)
UI 和使用者體驗 原生 OS 底部功能表和鍵盤自動填入整合 專屬的精簡瀏覽器分頁,用於驗證 內嵌網頁,搭配原生 OS 底部功能表
自動填入和條件式 UI 支援 (Credential Manager 自動填入) 支援 (WebAuthn 條件式 UI) 不支援
工作階段和憑證共用 使用 assetlinks.json 和共用 rpId,在網站和應用程式之間共用密碼金鑰 (不共用 Chrome Cookie) 與 Chrome 共用 Cookie 和憑證狀態 (可透過暫時瀏覽功能停用) 使用 assetlinks.json 共用密碼金鑰,但與 Chrome 的 Cookie 和工作階段隔離
Digital Asset Links (assetlinks.json) 依賴方網域必須提供 重新導向 URI 網域必須具備 HTTPS 重新導向功能 (建議使用,自訂配置則不需具備) 必須在依賴方網域上使用 (無法與外部或第三方 IdP 搭配使用)

Credential Manager

如果 Android 應用程式有原生登入或註冊畫面,建議優先使用 Credential Manager Jetpack 程式庫。

Credential Manager 的主要優點是,它將密碼金鑰、密碼和「使用 Google 帳戶登入」功能整合到單一、簡化的系統底部功能表中。使用者登入時,只要輕觸一下即可完成生物辨識驗證,不必離開應用程式,進而減少登入阻礙。即使使用者關閉初始底部功能表,並輕觸使用者名稱或密碼輸入欄位,您也可以使用 PendingGetCredentialRequest,直接在鍵盤或下拉式自動填入建議中顯示密碼金鑰、密碼和「使用 Google 帳戶登入」。這個備用方案提供與 WebAuthn 條件式 UI 相當的原生自動填入整合。

Credential Manager 底部功能表,顯示密碼金鑰、「使用 Google 帳戶登入」和密碼選項。
圖 1. Credential Manager 將密碼金鑰、「使用 Google 帳戶登入」和密碼整合至系統底部功能表。

Credential Manager 也提供與現代網頁密碼金鑰生命週期功能完全相同的功能。Credential Manager 可讓您執行下列操作:

搭載 Android 9 (API 級別 28) 以上版本的裝置支援密碼金鑰,而密碼等其他憑證則可透過 Google Play 服務,在較低版本的 Android 裝置上繼續使用。在 Android 14 (API 級別 34) 以上版本中,Credential Manager 也支援使用者選取的任何第三方憑證提供者。其他功能 (例如以 View 為基礎的自動填入整合 (PendingGetCredentialRequest) 和 Signal API) 則需要 Android 15 (API 級別 35) 以上版本。

在網站和應用程式之間共用憑證

首先,請按照「必要條件」一節的說明,在網域中託管 Digital Asset Links (assetlinks.json) 檔案,以便連結網站和 Android 應用程式。透過 assetlinks.json 連結網站和應用程式,代表兩者共用同一個仰賴方 ID (rpId),因此在 Chrome 網站上建立的密碼金鑰,可透過 Credential Manager 在原生 Android 應用程式中使用,而在應用程式中建立的密碼金鑰,則可在網站上使用。Credential Manager 會在網站和應用程式之間共用憑證;只有在您想重複使用網頁登入 UI 或 IdP 頁面時,才需要使用 Auth Tab。

如「建立密碼金鑰」一文所述,您也必須設定伺服器,驗證 Android 應用程式來源 (android:apk-key-hash:ENCODED_SHA256_HASH,格式為未填充 Base64URL 編碼的 APK 簽署憑證 SHA-256 雜湊)。如果應用程式有原生 UI,且您希望提供與 OS 整合的密碼金鑰登入體驗,請選擇 Credential Manager。

「驗證」分頁

許多服務會執行以 OAuth 或 OpenID Connect (OIDC) 建構的識別資訊提供者 (IdP) 微服務,或想在行動應用程式中重複使用現有的密碼金鑰網頁登入頁面。過去,應用程式會使用自訂分頁處理這些流程。自 Chrome 137 和 AndroidX Browser 1.9.0 起,Auth Tab 提供專為驗證流程設計的瀏覽器分頁。

Auth Tab 顯示精簡的瀏覽器登入介面,不含一般用途的瀏覽器選單項目。
圖 2. 驗證分頁會顯示專為驗證流程設計的瀏覽器介面。

標準自訂分頁是通用的應用程式內瀏覽器,會顯示與登入無關的 UI 元素,例如分享選單、書籤和「在 Chrome 中開啟」,可能會分散使用者注意力。此外,您還必須在資訊清單檔案中宣告意圖篩選器,才能接收驗證後重新導向、新增樣板程式碼,以及防範惡意應用程式攔截意圖。

Auth Tab 可解決這些驗證專屬問題。這項功能會移除不必要的瀏覽器 UI,例如最小化按鈕和分享選單,並提供只包含基本登入功能的專屬介面,包括密碼金鑰和密碼自動填入功能。Auth Tab 不會透過 OS 意圖轉送,而是使用自訂配置或透過 Digital Asset Links 驗證的 HTTPS 網址,直接將驗證重新導向傳送至應用程式內回呼,進而強化安全性並減少實作樣板。

工作階段共用和自訂分頁備用方案

根據預設,Auth Tab 也會直接與系統 Chrome 瀏覽器共用 Cookie 和憑證狀態。這樣一來,應用程式就能利用 Chrome 中有效的登入工作階段,並照常執行現有的 WebAuthn 實作,包括條件式 UI 和即時 UI 模式 (相當於 Credential Manager 的 preferImmediatelyAvailableCredentials)。相反地,如果您的用途需要獨立的驗證工作階段,不與瀏覽器共用 Cookie 或瀏覽記錄,可以呼叫 AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true) 啟用暫時瀏覽。

雖然您在應用程式中綁定 androidx.browser:browser (1.9.0 以上版本),但驗證分頁是否會在執行階段執行,取決於使用者的預設瀏覽器。如果預設瀏覽器是 Chrome 137 以下版本,或是不支援 Auth Tab 的第三方瀏覽器,Auth Tab 會自動改為啟動標準自訂分頁。發生這種備用情況時,驗證後重新導向會透過 AndroidManifest.xml 中的意圖篩選器傳回,就像在標準自訂分頁中一樣,而不是透過 Auth Tab 的回呼 (ActivityResultCallback)。在正式環境中,Google 建議您事先使用 CustomTabsClient.isAuthTabSupported(context, provider) 檢查預設瀏覽器支援,以便分支流程,或保留資訊清單意圖篩選器,讓應用程式可以處理任一路徑的結果。如需具體的備用實作範例,請參閱 Android 瀏覽器輔助程式。

OAuth 和 OIDC 安全性規定

驗證分頁只會保護及簡化從瀏覽器重新導向回應用程式的用戶端管道,不會自動保護 OAuth 或 OIDC 通訊協定本身。特別是考量到自訂分頁的備用行為,您必須遵循原生應用程式的 OAuth 2.0 (RFC 8252)。具體來說,請使用 code_challenge 和 code_verifier 參數結合 PKCE (Proof Key for Code Exchange,RFC 7636),防止授權碼攔截、state 參數驗證,以防止跨網站偽造要求 (CSRF) 和工作階段固定攻擊,以及 OpenID Connect 中的 nonce 參數產生和驗證,以防止 ID 權杖重送攻擊。有了這些保護措施,Google 建議將網頁式登入架構從標準自訂分頁遷移至驗證分頁。

WebView

部分應用程式採用混合式 WebView 架構,因此無法單獨將登入畫面拆分為原生 UI (Credential Manager) 或瀏覽器分頁 (Auth Tab)。在這種情況下,您可以直接在 WebView 中啟用 WebAuthn 支援。

如要在 WebView 中使用密碼金鑰,請將 AndroidX WebKit 程式庫 (androidx.webkit:webkit 1.12.0 以上版本) 和 Credential Manager 依附元件 (androidx.credentials:credentials 和 androidx.credentials:credentials-play-services-auth) 新增至 build.gradle 檔案。接著,使用 WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) 檢查功能支援,並呼叫 WebSettingsCompat.setWebAuthenticationSupport(webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP) 明確啟用 WebAuthn 支援。這項設定會自動將 WebView 網頁的密碼金鑰建立和驗證要求,橋接至 Credential Manager。

網域和使用者體驗限制

與原生 Credential Manager 整合一樣,您必須按照必要條件,在依賴方網域上託管 Digital Asset Links (assetlinks.json) 檔案,以便與應用程式建立關聯。您的伺服器會收到 android:apk-key-hash:ENCODED_SHA256_HASH (Base64URL 編碼的 SHA-256 憑證雜湊) 做為來源。由於這種方法需要在依賴方網域上託管 assetlinks.json,才能信任 Android 應用程式的簽署憑證,因此只有在您控制依賴方網頁網域 (第一方網頁登入) 時才適用。如果驗證流程會重新導向至外部或第三方 IdP,而您無法在該處為應用程式套件託管 assetlinks.json,則必須使用 Auth Tab (或透過 Credential Manager 使用原生「使用 Google 帳戶登入」功能),而非 WebView。

請注意兩項使用者體驗和功能限制:WebView 不支援條件式 UI (使用者聚焦於輸入欄位時,mediation: "conditional" 自動填入整合),也不會與系統 Chrome 瀏覽器共用 Cookie 或登入工作階段。基於這些限制,Google 建議在設計新的驗證流程時,使用 Credential Manager 或驗證分頁。不過,如果您想在現有的第一方混合式應用程式中加入密碼金鑰支援,而不進行重大架構變更,可以將密碼金鑰與 WebView 整合。

摘要

從應用程式目前的 UI 和驗證基礎架構著手,有助於選擇合適的密碼金鑰方法:

  • 如果應用程式有原生登入 UI,且您希望提供與 OS 整合的體驗,不必切換至瀏覽器畫面,請選擇 Credential Manager,使用密碼金鑰登入。
  • 如果您經營 OAuth 或 OIDC IdP 微服務、重新導向至外部 IdP,或想重複使用現有支援密碼金鑰的網頁登入頁面 (包括條件式 UI),並與 Chrome 共用有效的瀏覽器工作階段,請採用 Auth Tab,並實作 OAuth 2.0 for 原生應用程式 (RFC 8252) 中的安全性規定,特別是 PKCE、state 和 nonce。
  • 如果應用程式是以混合式 WebView 架構建構,且登入程序必須在內嵌的第一方網頁畫面中進行,請使用 WebView,但請注意,這不支援條件式 UI 和獨立 Cookie。

後續步驟