憑證管理工具 - 持有者 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-alpha02"

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，內含與驗證者要求相關的所有資訊。主要有三個元件：

最常見的情況是，驗證者會提出數位憑證呈現要求，因此您可以透過下列程式碼範例處理要求：

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()

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