憑證管理工具 - 持有者 API

Android 應用程式可透過 Credential Manager - Holder API 管理數位憑證，並向驗證者出示。

開始使用

如要使用 Credential Manager - Holder API，請將下列依附元件新增至應用程式模組的建構指令碼：

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

向 Credential Manager 註冊憑證

錢包必須註冊憑證中繼資料，憑證管理工具才能在收到要求時篩選憑證，並在憑證選取器中顯示。

圖片：顯示憑證管理工具中的數位憑證使用者介面
圖 1. 數位憑證使用者介面。

認證管理工具選取器 UI

這項中繼資料的格式會傳遞至 RegisterCredentialsRequest。建立 [RegistryManager][1] 並註冊憑證：

在本範例中，中繼資料是從憑證項目資料庫編譯而來。您可以在範例錢包中找到參考資料，該錢包會在應用程式載入時註冊中繼資料。日後 Jetpack API 將支援憑證資料庫組合。此時，您可以將憑證中繼資料註冊為定義明確的資料結構。

登錄檔會在裝置重新啟動後保留。重新註冊相同 ID + 類型登錄時，系統會覆寫先前的登錄記錄。因此，只有在憑證資料變更時，才需要重新註冊。

選用：建立比對器

憑證管理工具與通訊協定無關，會將中繼資料登錄視為不透明的 Blob，不會驗證或檢查其內容。因此，錢包必須提供比對器，也就是可執行的二進位檔，能夠處理錢包本身的資料，並根據傳入的要求產生顯示中繼資料。憑證管理工具會在沒有網路或磁碟存取的沙箱環境中執行比對工具，確保在向使用者顯示 UI 之前，不會有任何內容洩漏至錢包。

Credential Manager API 會提供熱門通訊協定的比對器，目前為 OpenID4VP。這項功能尚未正式發布，因此目前請使用 OpenID4VP 通訊協定的範例比對器。

處理所選憑證

接著，錢包需要處理使用者選取憑證的情況。您可以定義監聽 androidx.credentials.registry.provider.action.GET_CREDENTIAL 意圖篩選器的 Activity。我們的範例錢包示範了這項程序。

啟動活動的意圖會包含驗證者要求和呼叫來源，這些資訊可使用 PendingIntentHandler.retrieveProviderGetCredentialRequest 函式擷取。API 會傳回 ProviderGetCredentialRequest，內含與指定驗證者要求相關的所有資訊。有三個主要元件：

  • 提出要求的應用程式。您可以使用 getCallingAppInfo 擷取這項資訊。
  • 所選憑證。您可以透過selectedEntryId 擴充方法，取得使用者選擇的候選人資訊；這會與您註冊的憑證 ID 相符。
  • 驗證人員提出的任何特定要求。您可以透過 getCredentialOptions 方法取得這項資訊。在這種情況下，您應該會在這個清單中找到 GetDigitalCredentialOption，其中包含數位憑證要求。

驗證者最常提出數位憑證「出示」要求，因此您可以透過下列範例程式碼處理這類要求：

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

如需相關範例，請參閱範例錢包。

算繪錢包 UI

選取憑證後，系統會叫用錢包，並引導使用者完成錢包 UI 流程。在範例中，這是生物辨識提示。

傳回憑證回應

錢包準備好傳回結果後，您可以使用憑證回應完成活動，藉此傳回結果：

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

如有例外情形，您同樣可以傳送憑證例外狀況：

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

如要瞭解如何在結構定義中傳回憑證回應，請參閱範例應用程式。