讓憑證與憑證提供者保持一致

使用者建立密碼金鑰時，憑證提供者伺服器會儲存特定詳細資料，而憑證提供者 (例如 Google 密碼管理工具) 則會儲存其他資料。具體情形如下：

• 信賴方伺服器會儲存公開金鑰憑證。
• 憑證供應商會儲存使用者名稱、顯示名稱、私密金鑰， 以及其他相關中繼資料。這項中繼資料可協助使用者在登入時識別及選取所需密碼金鑰。

如果依賴方伺服器上儲存的資料與憑證提供者不一致，可能會導致使用者體驗不佳。下列情況可能會發生問題：

• 憑證在憑證提供者伺服器上遭到刪除，但憑證提供者並未刪除，導致憑證提供者向使用者顯示已刪除的憑證。
• 依賴方伺服器上的使用者名稱或顯示名稱已更新，但憑證提供者未更新，導致憑證提供者顯示過時的詳細資料。

憑證管理工具的 Signal API 可讓信賴方與憑證提供者通訊，以便刪除憑證及更新使用者中繼資料，例如使用者名稱和顯示名稱。系統支援三種要求類型，適用於不同情境：

• SignalUnknownCredentialRequest

  • 表示特定憑證已失效，應從憑證供應商隱藏或移除。

• SignalAllAcceptedCredentialIdsRequest

  • 向憑證供應商提供可接受的憑證 ID 清單。

• SignalCurrentUserDetailsRequest

  • 更新使用者的中繼資料詳細資料。

版本相容性

Signal API 適用於搭載 Android 15 以上版本的裝置，並從 androidx.credentials 程式庫的 1.6.0-beta03 版開始提供。

實作

如要使用 Signal API，請按照下列步驟操作：

1. 在專案中新增憑證管理工具依附元件。

   Kotlin

   dependencies {
       implementation("androidx.credentials:credentials:1.6.0-rc02")
   }

   Groovy

   dependencies {
       implementation "androidx.credentials:credentials:1.6.0-rc02"
   }

2. 呼叫 Signal API

   如要將信號要求傳送至憑證提供者，請使用支援的信號要求。如以下範例所示，每種信號要求類型都需要 JSON 要求：

   • 不明憑證 (SignalUnknownCredentialRequest)

     使用 SignalUnknownCredentialRequest 表示憑證遭到拒絕，且系統視為不明。憑證提供者收到這項信號時，會隱藏或刪除憑證。

     用法

     如果憑證方無法驗證密碼金鑰聲明，請使用這項信號。這表示密碼金鑰無效，憑證提供者必須隱藏或移除密碼金鑰。

     這項要求必須提供 rpId 和 credentialId JSON 參數。如要進一步瞭解 JSON 結構，請參閱signalUnknownCredential 選項。

     credentialManager.signalCredentialState(
         SignalUnknownCredentialRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("credentialId", credentialId /* [String] Credential ID of the credential to be hidden or deleted */)
             }.toString()
         )
     )
     

   • 所有可接受的憑證 (SignalAllAcceptedCredentialIdsRequest)

     使用 SignalAllAcceptedCredentialIdsRequest 通知憑證供應商所有已接受的憑證。憑證供應商收到信號後，會隱藏或刪除不在清單中的憑證，或取消隱藏現在列於清單中的憑證。

     用法

     如果密碼金鑰驗證失敗，請使用這項信號。這項失敗表示密碼金鑰無效，憑證提供者必須隱藏或移除密碼金鑰。您也可以在需要將已知憑證 ID 集播送給憑證供應商時，使用這項信號。

     這項要求所需的 JSON 參數為 rpId、userId 和 allAcceptedCredentialIds。如要進一步瞭解 JSON 結構，請參閱 signalAllAcceptedCredential 選項。

     credentialManager.signalCredentialState(
         SignalAllAcceptedCredentialIdsRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("userId", userId /* [String] User ID of the current user */)
                 put(
                     "allAcceptedCredentialIds",
                     JSONArray(credentialIdsList /* [List<String>] List of accepted Credential IDs */)
                 )
             }.toString()
         )
     )
     

   • 目前使用者詳細資料 (SignalCurrentUserDetailsRequest)

     使用 SignalCurrentUserDetailsRequest 通知憑證供應商，指定使用者的中繼資料 (例如使用者名稱和顯示名稱) 已更新，應顯示在憑證供應商中。

     用法

     當使用者或信賴方更新與使用者帳戶相關聯的密碼金鑰中繼資料時，請使用這項信號。

     這項要求所需的 JSON 參數為 rpId、userId、name 和 displayName。如要進一步瞭解 JSON 結構，請參閱 signalCurrentUserDetails 選項。

     credentialManager.signalCredentialState(
         SignalCurrentUserDetailsRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("userId", userId /* [String] User ID of the current user */)
                 put("name", name /* [String] New Name to be updated for the current user */)
                 put("displayName", displayName /* [String] New display name to be updated for the current user */)
             }.toString()
         )
     )
     

測試實作成果

如要測試訊號 API 的導入情況，請完成下列步驟：

1. 安裝名為「MyVault」的憑證提供者範例。

2. 依序前往「設定」>「密碼、密碼金鑰與帳戶」>「偏好的服務」，啟用 MyVault 做為憑證提供者。

   

3. 依序前往「設定」 >「應用程式」 >「MyVault」 >「通知」，啟用 MyVault 的所有通知。

   

4. 依序前往「設定」 >「應用程式」 >「MyVault」 >「通知」 >「類別」 >「Signal API 通知管道」，確認「在畫面上彈出」已開啟。

   

5. 在應用程式中，觸發將信號要求傳送至憑證供應商的流程。畫面上應該會顯示 MyVault 的通知。 這會驗證憑證供應商是否收到要求。