Online
ID digital dapat diterima dalam alur dalam aplikasi dan web. Untuk menerima kredensial dari Google Wallet, Anda harus:
- Integrasikan menggunakan aplikasi atau web dengan mengikuti petunjuk yang diberikan dan
- Isi formulir ini untuk meminta dan menyetujui persyaratan layanan penerimaan kredensial dari Google Wallet.
Prasyarat
Untuk menguji presentasi ID, Anda harus mendaftar ke program beta publik terlebih dahulu menggunakan akun pengujian yang diinginkan. Selanjutnya, berikan detail yang dihasilkan kepada kontak Google yang ditetapkan bagi Anda.
- Link Persyaratan Layanan
- Logo
- Situs
- ID paket Play Store (untuk integrasi aplikasi Android)
- ID Gmail yang digunakan untuk bergabung ke versi beta publik
Format Kredensial yang Didukung
Ada beberapa standar yang diusulkan yang menentukan format data dokumen identitas digital, dengan dua standar yang mendapatkan daya tarik industri yang signifikan:
- mdocs - ditentukan oleh ISO.
- Kredensial Verifikasi W3C - ditentukan oleh W3C.
Meskipun Pengelola Kredensial Android mendukung kedua format tersebut, Google Wallet saat ini hanya mendukung ID Digital berbasis mdoc.
Pengalaman pengguna
Saat aplikasi meminta atribut identitas, proses berikut akan terjadi:
Penemuan Kredensial: Aplikasi membuat kueri pada dompet yang tersedia untuk mengidentifikasi kredensial yang dapat memenuhi permintaan. Android kemudian menampilkan pemilih UI sistem, yang menampilkan informasi yang akan dibagikan. Hal ini memungkinkan pengguna membuat keputusan yang tepat tentang kredensial yang akan digunakan.
Pemilihan Pengguna dan Interaksi Wallet: Pengguna memilih kredensial, dan Android memanggil aplikasi wallet yang sesuai untuk menyelesaikan transaksi. Aplikasi Wallet dapat menampilkan layar izinnya sendiri atau memerlukan konfirmasi biometrik.
Hasil: Jika pengguna mengizinkan, kredensial identitas yang dipilih akan dibagikan dengan aplikasi yang meminta. Jika pengguna menolak, error akan ditampilkan.
Dalam Aplikasi
Untuk meminta kredensial identitas dari aplikasi Android Anda, ikuti langkah-langkah berikut:
Memperbarui dependensi
Dalam build.gradle project, perbarui dependensi untuk menggunakan Pengelola Kredensial (beta):
dependencies {
implementation("androidx.credentials:credentials:1.5.0-beta01")
// optional - needed for credentials support from play services, for devices running Android 13 and below.
implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01")
}
Mengonfigurasi Pengelola Kredensial
Untuk mengonfigurasi dan melakukan inisialisasi objek CredentialManager, tambahkan logika yang mirip dengan berikut ini:
// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = CredentialManager.create(context)
Meminta Atribut identitas
Daripada menentukan parameter individual untuk permintaan identitas, aplikasi menyediakan semuanya bersama-sama sebagai string JSON dalam CredentialOption. Pengelola Kredensial meneruskan string JSON ini ke dompet digital yang tersedia tanpa memeriksa kontennya. Setiap dompet kemudian bertanggung jawab untuk: - Mengurai string JSON untuk memahami permintaan identitas. - Menentukan kredensial yang disimpan, jika ada, yang memenuhi permintaan.
W3C diharapkan akan secara resmi menentukan struktur permintaan JSON ini sebagai bagian dari spesifikasi API web. Namun, penting untuk diingat bahwa spesifikasi ini dalam bentuk draf dan dapat berubah sewaktu-waktu.
Awalnya, kami akan menggunakan protokol pratinjau untuk mendapatkan ID dari Google Wallet. Hal ini memungkinkan kita memulai integrasi dan pengujian saat spesifikasi API web diselesaikan.
Berikut adalah contoh requestJson mdoc untuk protokol pratinjau:
{
identity: {
providers: [{
holder: {
selector: {
format: ['mdoc'],
type: 'org.iso.18013.5.1.mDL',
fields: [
'org.iso.18013.5.1.family_name',
'org.iso.18013.5.1.portrait',
]
},
params: {
nonce: '1234',
readerPublicKey: '<public_key>',
extraParamAsNeededByWallets: true,
},
},
}]
}
}
// The request in the JSON format to conform with
// the JSON-ified Digital Credentials API request definition.
val requestJson = generateRequestFromServer()
val digitalCredentialOption =
GetDigitalCredentialOption(requestJson = requestJson)
// Use the option from the previous step to build the `GetCredentialRequest`.
val getCredRequest = GetCredentialRequest(
listOf(digitalCredentialOption)
)
coroutineScope.launch {
try {
val result = credentialManager.getCredential(
context = activityContext,
request = getCredRequest
)
verifyResult(result)
} catch (e : GetCredentialException) {
handleFailure(e)
}
}
// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
val credential = result.credential
when (credential) {
is DigitalCredential -> {
val responseJson = credential.credentialJson
validateResponseOnServer(responseJson)
}
else -> {
// Catch any unrecognized credential type here.
Log.e(TAG, "Unexpected type of credential ${credential.type}")
}
}
}
// Handle failure.
fun handleFailure(e: GetCredentialException) {
when (e) {
is GetCredentialCancellationException -> {
// The user intentionally canceled the operation and chose not
// to share the credential.
}
is GetCredentialInterruptedException -> {
// Retry-able error. Consider retrying the call.
}
is NoCredentialException -> {
// No credential was available.
}
is CreateCredentialUnknownException -> {
// An unknown, usually unexpected, error has occurred. Check the
// message error for any additional debugging information.
}
is CreateCredentialCustomException -> {
// You have encountered a custom error thrown by the wallet.
// If you made the API call with a request object that's a
// subclass of CreateCustomCredentialRequest using a 3rd-party SDK,
// then you should check for any custom exception type constants
// within that SDK to match with e.type. Otherwise, drop or log the
// exception.
}
else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
}
}
Respons menampilkan identityToken (string JSON), yang ditentukan oleh W3C. Aplikasi Wallet bertanggung jawab untuk membuat respons ini.
Contoh:
{
"token": "<base64 encoded response>"
}
Mengirim token dan memprosesnya di server
Setelah menerima identityToken, aplikasi Anda harus mengirimkannya ke server aplikasi untuk diverifikasi. Langkah awal melibatkan decoding token dari format base64. Array byte yang dihasilkan mewakili data CBOR, yang mematuhi CDDL berikut.
CredentialDocument = {
"version": tstr, // Set to "ANDROID-HPKE-v1"
"pkEm": bstr, // Public key, in uncompressed form
"cipherText": bstr // The encrypted data
}
Langkah berikutnya adalah menghitung SessionTranscript dari ISO/IEC 18013-5:2021 dengan struktur Handover khusus Android:
SessionTranscript = [
null, // DeviceEngagementBytes not available
null, // EReaderKeyBytes not available
AndroidHandover // Defined below
]
AndroidHandover = [
"AndroidHandoverv1", // Version number
nonce, // nonce that comes from request
appId, // RP package name
pkRHash, // The SHA256 hash of the recipient public key
]
cipherText dienkripsi menggunakan enkripsi HPKE. Untuk mendekripsinya, gunakan SessionTranscript sebagai Data Autentikasi Tambahan, bersama dengan kunci pribadi EC yang dibuat sebelumnya, dan setelan berikut:
- KEM: DHKEM(P-256, HKDF-SHA256)
- KDF: HKDF-SHA256
- AEAD: AES-128-GCM
Cleartext yang dihasilkan adalah byte CBOR DeviceResponse seperti yang ditentukan dalam ISO/IEC 18013-5:2021. DeviceResponse harus divalidasi sesuai dengan klausul 9 ISO/IEC 18013-5:2021. Hal ini mencakup beberapa langkah, seperti memverifikasi bahwa mdoc berasal dari penerbit tepercaya dan bahwa respons ditandatangani oleh perangkat yang dimaksud. Class DeviceResponseParser dari project Kredensial Identitas OpenWallet Foundation dapat digunakan untuk bagian dari proses validasi ini.
Web
Untuk meminta Kredensial Identitas menggunakan Digital Credentials API di Chrome, Anda harus mendaftar ke uji coba origin Digital Credentials API.
Tatap Muka
Menerima tanda pengenal dari Google Wallet memerlukan langkah-langkah berikut:
- Membuat atau memperoleh pembaca untuk menerima ID seperti yang ditentukan oleh ISO 18013-5
- Memuat sertifikat IACA ke pembaca untuk memastikan ID yang diterima bersifat autentik
- Menguji solusi Anda
- Mendaftarkan aplikasi Anda ke Google Wallet
Membuat atau memperoleh pembaca untuk menerima ID seperti yang ditentukan oleh ISO 18013-5
ID di Wallet diterapkan sesuai dengan standar ISO 18013-5 untuk SIM seluler. Keduanya menggunakan interaksi kode QR atau berbasis NFC bersama dengan BLE sebagai mekanisme transfer data - sehingga perangkat apa pun yang dapat menerapkan aspek standar tersebut dapat berfungsi sebagai pembaca, bahkan aplikasi seluler. Karena standar ini bersifat terbuka, ada beberapa penerapan pihak ketiga yang tersedia di pasar. Selain itu, Anda dapat menerapkan fungsi tersebut secara langsung jika diperlukan.
Untuk panduan cara menerapkan fungsi ini sendiri, lihat aplikasi Android pembaca referensi open source kami, yang menerapkan standar ISO dan dapat menerima mDL dari Google Wallet.
Anda dapat memulai dengan mem-build dan menjalankan aplikasi pembaca referensi:
- Meng-clone repositori aplikasi referensi
- Buka project di Android Studio
- Build dan jalankan target
appverifierdi perangkat Android atau emulator.
Memuat sertifikat IACA ke pembaca untuk memastikan ID yang diterima bersifat autentik
Untuk memvalidasi kredensial yang sebenarnya, Anda harus memiliki tanda pengenal di dompet dari penerbit yang didukung. Daftar penerbit yang didukung oleh Google Wallet diberikan di bawah ini beserta link ke sertifikat mereka untuk verifikasi.
- Arizona
- California
- Colorado
- Georgia
- Maryland
- New Mexico #### Uji solusi Anda
Untuk menguji solusi Anda, build dan jalankan aplikasi Android holder referensi open source kami. Berikut adalah langkah-langkah untuk mem-build dan menjalankan aplikasi holder referensi:
- Meng-clone repositori aplikasi referensi
- Buka project di Android Studio
- Build dan jalankan target
appholderdi perangkat Android atau emulator.
(Opsional) Mendaftarkan aplikasi Anda ke Google Wallet
Daftarkan aplikasi Anda ke Google Wallet dengan mengisi formulir ini.