Menangani penerbitan kredensial dengan aplikasi pemegang Anda

Untuk menerima dan menyimpan kredensial dari penerbit, aplikasi pemegang Anda harus menangani alur penerbitan. Penerbitan kredensial dapat dipicu dengan dua cara:

  • Alur yang dimulai penerbit: pengguna memicu permintaan untuk menerbitkan VDC dari aplikasi atau situs penerbit. Misalnya, situs dapat menawarkan opsi kepada penggunanya untuk "Menambahkan paspor ke dompet". Penerbit memanggil Credential Manager issuance API untuk membuat permintaan Penawaran Kredensial OpenID4VCI. Untuk menangani permintaan tersebut, pemegang harus terlebih dahulu berintegrasi dengan Credential Manager untuk mendaftarkan metadatanya. Pengelola Kredensial akan menampilkan opsi yang relevan untuk dipilih pengguna. Setelah pengguna memilih opsi pemegang, aplikasi pemegang akan dipanggil dan dapat melanjutkan langkah-langkah yang diperlukan untuk menyelesaikan penerbitan.
  • Alur yang dimulai pemegang: pengguna meminta untuk menambahkan VDC dari aplikasi pemegang. Misalnya, pemegang dapat menawarkan tombol untuk "Menambahkan paspor Anda". Dalam hal ini, pemegang mengelola daftar penerbit dan metadata yang didukungnya. Aplikasi ini tidak perlu berintegrasi dengan Pengelola Kredensial Android untuk menyelesaikan fungsi ini.

Untuk mengetahui informasi selengkapnya tentang cara kerja kredensial dengan Holder API, lihat Tentang menyimpan kredensial digital.

Kompatibilitas versi Android

Holder API didukung di Android 6 (API level 23) dan yang lebih tinggi.

Penerapan

Untuk menggunakan Credential Manager Holder API, tambahkan dependensi berikut ke skrip build modul aplikasi Anda:

Groovy

dependencies {
    // Use to implement credentials registrys

    implementation "androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04"

}

Kotlin

dependencies {
    // Use to implement credentials registrys

    implementation("androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04")

}

Membuat RegistryManager

Buat instance RegistryManager dan daftarkan permintaan RegisterCreationOptionsRequest dengannya.

val registryManager = RegistryManager.create(context)

try {
    registryManager.registerCreationOptions(object :
        RegisterCreationOptionsRequest(
            creationOptions = buildIssuanceData(),
            matcher = loadIssuanceMatcher(),
            type = DigitalCredential.TYPE_DIGITAL_CREDENTIAL,
            id = "openid4vci",
        ) {}
    )
} catch (e: Exception) {
    Log.e(TAG, "Issuance registration failed.", e)
}

Matcher adalah file biner WebAssembly (Wasm) yang menerima creationOptions yang ditetapkan selama pendaftaran dan penawaran kredensial yang dikirim oleh penerbit untuk menentukan entri yang ditampilkan di UI Credential Manager. Lihat aplikasi dompet contoh open source untuk mengetahui contoh pencocok.

Menangani permintaan penerbitan

Selanjutnya, dompet perlu menangani saat opsi pembuatan kredensial dipilih oleh pengguna. Tentukan aktivitas yang memproses filter intent androidx.credentials.registry.provider.action.CREATE_CREDENTIAL, seperti yang ditunjukkan dalam contoh dompet.

Intent yang meluncurkan aktivitas berisi permintaan pembuatan dan origin panggilan, yang dapat Anda ekstrak dengan fungsi PendingIntentHandler.retrieveProviderCreateCredentialRequest. API akan menampilkan ProviderCreateCredentialRequest yang berisi semua informasi yang terkait dengan permintaan pembuatan. Ada dua komponen utama:

  • Aplikasi yang membuat permintaan. Anda dapat mengambilnya dengan getCallingAppInfo.
  • Permintaan dari aplikasi panggilan. Anda dapat mengambilnya dengan getCallingRequest, yang menampilkan CreateCredentialRequest. Jika permintaan ditujukan untuk kredensial digital, permintaan tersebut adalah instance CreateDigitalCredentialRequest, yang berisi JSON permintaan penerbitan di properti requestJson. Anda dapat memprosesnya dengan kode contoh berikut:
val pendingIntentRequest =
    PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val request = pendingIntentRequest!!.callingRequest
if (request is CreateDigitalCredentialRequest) {
    Log.i(TAG, "Got DC creation request: ${request.requestJson}")
    processCreationRequest(request.requestJson)
}

Pengesahan kunci

Perhatikan hal-hal berikut tentang pengesahan kunci:

  • Saat membuat pengesahan kunci, Anda mungkin menggunakan BigInteger.toByteArray untuk mengonversi materi kunci menjadi, misalnya, kunci web JSON. Metode ini terkadang dapat menambahkan byte tanda dan menyebabkan error validasi. Jika hal ini terjadi, hapus byte ini sebelum mengirim pengesahan kunci ke penerbit.
  • Sebaiknya gunakan android_key_attestation sebagai jenis bukti kunci.

Menampilkan respons pembuatan

Setelah dompet menyelesaikan langkah-langkah yang diperlukan untuk menyimpan kredensial, selesaikan aktivitas dengan respons kredensial:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialResponse(
    resultData,
    CreateDigitalCredentialResponse(response.responseJson)
)
setResult(RESULT_OK, resultData)
finish()

Jika ada pengecualian, Anda juga dapat mengirim pengecualian kredensial:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialException(
    resultData,
    CreateCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

Untuk melihat contoh lengkap menampilkan respons kredensial dalam konteks, lihat aplikasi contoh.