Panduan ini menjelaskan cara menggunakan DigitalCredential API untuk mendapatkan nomor telepon terverifikasi bagi pengguna Anda. Proses ini melibatkan dua langkah:
- Meminta
TS.43 token
: Aplikasi klien Anda ("verifier") meminta token TS.43 sementara dari perangkat pengguna.TS.43 token
adalah kredensial yang dikeluarkan operator yang mewakili identitas pengguna. - Menukarkan token dengan nomor telepon: Backend aplikasi Anda menukarkan
TS.43 token
dengan agregator atau operator untuk mendapatkan nomor telepon terverifikasi pengguna.
Prasyarat
Untuk menerapkan verifikasi nomor telepon dengan DigitalCredential API, Anda memerlukan akun dengan agregator. Agregator berinteraksi dengan operator dan menyediakan permukaan API yang diperlukan untuk aplikasi Anda, biasanya sebagai endpoint API cloud yang dapat ditagih.
Anda juga perlu menambahkan dependensi berikut ke skrip build Gradle:
Kotlin
dependencies { implementation("androidx.credentials:credentials:1.6.0-alpha05") implementation("androidx.credentials:credentials-play-services-auth:1.6.0-alpha05") }
Groovy
dependencies { implementation "androidx.credentials:credentials:1.6.0-alpha05" implementation "androidx.credentials:credentials-play-services-auth:1.6.0-alpha05" }
Implementasi
Proses end-to-end umumnya mengikuti langkah-langkah berikut:
- Meminta parameter DCQL (Digital Credential Query Language) dari agregator: Panggil satu atau beberapa agregator dan minta serangkaian parameter DCQL. DCQL memungkinkan Anda menentukan kredensial digital yang tepat yang Anda butuhkan dari setiap agregator.
Buat permintaan OpenID4VP: Dari backend aplikasi Anda, buat permintaan OpenID4VP, sambil menyertakan parameter DCQL dari pengagregasi. Kemudian, kirim permintaan OpenID4VP ke aplikasi klien Anda.
Panggil Credential Manager API: Di aplikasi klien Anda, gunakan Credential Manager API untuk mengirim permintaan OpenID4VP ke sistem operasi. Sebagai respons, Anda akan menerima objek respons OpenID4VP yang berisi
TS.43 Digital Credential
. Kredensial ini dienkripsi dan hanya dapat didekripsi oleh agregator terkait. Setelah menerima token operator, kirim respons dari aplikasi klien Anda ke backend aplikasi.Memvalidasi respons: Di backend aplikasi Anda, validasi respons OpenID4VP.
Tukar dengan nomor telepon: Dari backend aplikasi Anda, kirim
TS.43 Digital Credential
ke agregator. Agregator memvalidasi kredensial dan menampilkan nomor telepon yang telah diverifikasi.
Meminta parameter DCQL dari agregator
Dari backend aplikasi Anda, kirim permintaan ke agregator untuk objek kredensial Digital Credential Query Language (DCQL). Pastikan untuk memberikan nonce dan ID permintaan dalam permintaan Anda. Agregator menampilkan objek kredensial DCQL, yang memiliki struktur yang mirip dengan berikut ini:
{
// The credential ID is mapped to the request ID that is sent in your request to the aggregator.
"id": "aggregator1",
"format": "dc-authorization+sd-jwt",
"meta": {
"vct_values": [
"number-verification/device-phone-number/ts43"
],
"credential_authorization_jwt": "..."
},
"claims": [
{
"path": ["subscription_hint"],
"values": [1]
},
{
"path": ["phone_number_hint"],
"values": ["+14155552671"]
}
]
}
Buat permintaan OpenID4VP
Pertama, dari backend aplikasi Anda, buat objek dcql_query
dengan menempatkan objek kredensial DCQL dalam array credentials
yang berada dalam objek dcql_query
seperti yang ditunjukkan dalam contoh berikut:
"dcql_query": {
"credentials": [
"id": "aggregator1",
"format": "dc-authorization+sd-jwt",
"meta": {
"vct_values": [
"number-verification/device-phone-number/ts43"
],
"credential_authorization_jwt": "..."
},
"claims": [
{
"path": ["subscription_hint"],
"values": [1]
},
{
"path": ["phone_number_hint"],
"values": ["+14155552671"]
}
]
]
}
Kemudian, buat permintaan OpenID4VP dengan struktur berikut:
{
"protocol": "openid4vp-v1-unsigned",
"data": {
"response_type": "vp_token",
"response_mode": "dc_api",
"nonce": "...",
"dcql_query": { ... }
}
}
protocol
: Harus disetel keopenid4vp-v1-unsigned
untuk permintaan verifikasi nomor telepon.response_type
danresponse_mode
: Konstanta yang menunjukkan format permintaan dengan nilai tetapvp_token
dandc_api
.nonce
: Nilai unik yang dibuat oleh backend Anda untuk setiap permintaan. Nonce dalam objek kredensial DCQL aggregator harus cocok dengan nonce ini.dcql_query
: Dalam hal ini, gunakandcql_query
untuk menentukan bahwaTS.43 Digital Credential
sedang diminta. Anda juga dapat meminta kredensial digital lainnya di sini.
Kemudian, bungkus permintaan OpenID4VP dalam objek permintaan DigitalCredential API dan kirimkan ke aplikasi klien.
{
"requests":
[
{
"protocol": "openid4vp-v1-unsigned",
"data": {
"response_type": "vp_token",
"response_mode": "dc_api",
"nonce": "...",
"dcql_query": { ... }
}
}
]
}
Cuplikan berikut menunjukkan cara membuat permintaan DigitalCredential API:
def GenerateDCRequest():
credentials = []
aggregator1_dcql = call_aggregator_endpoint(nonce, "aggregator1", additional_params)
credentials.append(aggregator1_dcql) # You can optionally work with multiple
# aggregators, or request other types of credentials
val dc_request =
{
"requests":
[
{
"protocol": "openid4vp-v1-unsigned",
"data": {
"response_type": "vp_token",
"response_mode": "dc_api",
"nonce": "...",
"dcql_query": {"credentials": credentials}
}
}
]
}
return dc_request
Memanggil Credential Manager API
Di aplikasi klien Anda, lakukan panggilan ke Credential Manager API, dengan permintaan DigitalCredential API yang disediakan oleh backend aplikasi Anda.
val requestJson = generateTs43DigitalCredentialRequestFromServer()
val digiCredOption = GetDigitalCredentialOption(requestJson = requestJson)
val getCredRequest = GetCredentialRequest(
listOf(digiCredOption)
)
coroutineScope.launch {
try {
val response = credentialManager.getCredential(
context = activityContext,
request = getCredRequest
)
val credential = response.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}")
}
}
} catch (e : GetCredentialException) {
// If user cancels the operation, the feature isn't available, or the
// SIM doesn't support the feature, a GetCredentialCancellationException
// will be returned. Otherwise, a GetCredentialUnsupportedException will
// be returned with details in the exception message.
handleFailure(e)
}
}
Respons DigitalCredential API berisi respons OpenID4VP. JSON kredensial standar dari hasil DigitalCredential
adalah sebagai berikut:
{
"protocol": "openid4vp-v1-unsigned",
"data": {
"vp_token": {
"aggregator1": ["eyJhbGciOiAiRVMy..."] # The encrypted TS.43 Digital
# Credential in an array structure.
}
}
}
Dari aplikasi klien Anda, kirim respons DigitalCredential API kembali ke server backend tempat respons tersebut dapat divalidasi dan digunakan untuk menukarkan nomor telepon terverifikasi dengan agregator.
Memvalidasi respons Kredensial Digital
Berikut adalah contoh cara mengurai respons dan melakukan langkah validasi di backend aplikasi Anda:
def processDigitalCredentialsResponse(response):
# Step 1: Parse out the TS.43 Digital Credential from the response
openId4VpResponse = response['data']
ts43_digital_credential = response['vp_token']["aggregator1"][0]
# Step 2: Perform response validation
verifyResponse(ts43_digital_credential)
def verifyResponse(ts43_digital_credential):
# The returned ts43_digital_credential is an SD-JWT-based Verifiable Credentials
# (SD-JWT VC) as defined in this IETF spec. The section 3.4 of the specification
# outlines how to validate the credential. At a high level, the steps involves
# validating (1) the nonce in the response credential matches the one in the
# request, (2) the integrity of the credential by checking the credential is
# signed by the trusted issuer Android Telephony, and (3) other validity
# properties associated with this credential, such as issue time and expiration
# time
# In most cases, you can use an SD-JWT VC library to perform these validations.
# Some aggregators may also perform the validation logic for you. Check with your
# aggregator to decide the exact scope of the validation required.
Tukar dengan nomor telepon
Dari backend aplikasi Anda, kirim TS.43 Digital Credential
yang telah divalidasi ke endpoint agregator untuk memvalidasi kredensial dan menerima nomor telepon yang telah diverifikasi.
def processDigitalCredentialsResponse(response):
# ... prior steps
# Step 3: Call aggregator endpoint to exchange the verified phone number
callAggregatorPnvEndpoint(ts43_digital_credential)