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

使用者建立密碼金鑰時，仰賴端伺服器會儲存特定詳細資料，而 Google 密碼管理工具等憑證提供者則會儲存其他資料。具體內容如下：

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

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

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

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

• SignalUnknownCredentialRequest

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

• SignalAllAcceptedCredentialIdsRequest

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

• SignalCurrentUserDetailsRequest

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

版本相容性

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

導入作業

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

1. 在專案中新增 Credential Manager 依附元件。

   Kotlin

   dependencies {
       implementation("androidx.credentials:credentials:1.7.0-alpha02")
   }

   Groovy

   dependencies {
       implementation "androidx.credentials:credentials:1.7.0-alpha02"
   }

2. 呼叫 Signal API

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

   • 不明憑證 (SignalUnknownCredentialRequest)

     使用 SignalUnknownCredentialRequest 表示憑證遭到拒絕，並視為不明。憑證提供者收到這個信號後，會隱藏或刪除憑證。

     用量

     如果依賴方無法驗證密碼金鑰宣告，請使用這個信號。這表示密碼金鑰無效，憑證提供者必須隱藏或移除該金鑰。

     這項要求的必要 JSON 參數為 rpId 和 credentialId。如要進一步瞭解 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()
         )
     )
     

測試實作成果

如要測試 Signal API 導入作業，請完成下列步驟：

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

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

   

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

   

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

   

5. 在應用程式中，觸發將信號要求傳送至憑證提供者的流程。您應該會在畫面上看到 MyVault 的通知。這表示憑證供應商已收到要求。