Hướng dẫn này giải thích cách Bên tin cậy (RP) có thể tích hợp về mặt kỹ thuật API Thông tin xác thực kỹ thuật số để yêu cầu và xác thực Giấy phép lái xe trên thiết bị di động (mDL) và Thẻ giấy tờ tuỳ thân từ Google Wallet trên các ứng dụng Android và web.
Quy trình đăng ký và điều kiện tiên quyết
Trước khi phát hành công khai, bạn phải chính thức đăng ký ứng dụng Bên tin cậy với Google.
- Kiểm thử trong Hộp cát: Bạn có thể bắt đầu phát triển ngay bằng cách sử dụng Môi trường hộp cát và Tạo mã nhận dạng kiểm thử. Bạn không bắt buộc phải chấp nhận Điều khoản dịch vụ để kiểm thử.
- Gửi biểu mẫu tiếp nhận: Điền vào Biểu mẫu thiết lập RP. Quá trình thiết lập thường mất từ 3 đến 5 ngày làm việc. Tên và Logo sản phẩm của bạn sẽ xuất hiện trên màn hình xin phép dành cho người dùng để giúp người dùng xác định ai đang yêu cầu dữ liệu của họ.
- Chấp nhận Điều khoản dịch vụ: Bạn phải ký Điều khoản dịch vụ trước khi phát hành công khai.
Nếu bạn có câu hỏi về việc theo dõi đơn đăng ký hoặc kiểm thử từ các khu vực không được hỗ trợ, hãy xem Câu hỏi thường gặp.
Định dạng và tính năng được hỗ trợ
Google Wallet hỗ trợ Thẻ căn cước kỹ thuật số dựa trên **ISO mdoc**.
- Thông tin xác thực được hỗ trợ: Bạn có thể xem các thông tin xác thực và thuộc tính được hỗ trợ.
- Giao thức được hỗ trợ: OpenID4VP (Phiên bản 1.0).
- SDK Android tối thiểu: Android 9 (cấp độ API 28) trở lên.
- Trình duyệt được hỗ trợ: Để xem danh sách đầy đủ các trình duyệt hỗ trợ API Thông tin xác thực kỹ thuật số, hãy tham khảo trang Hỗ trợ hệ sinh thái.
- Câu hỏi thường gặp: Để biết các câu hỏi về phạm vi hỗ trợ theo quốc gia và tiến trình triển khai cho các khu vực mới, hãy xem Câu hỏi thường gặp về thông tin xác thực và dữ liệu.
Định dạng yêu cầu
Để yêu cầu thông tin xác thực từ bất kỳ ví nào, bạn phải định dạng yêu cầu bằng OpenID4VP. Bạn có thể yêu cầu thông tin xác thực cụ thể hoặc nhiều thông tin xác thực trong một đối tượng dcql_query.
Ví dụ về yêu cầu JSON
Sau đây là mẫu yêu cầu requestJson mdoc để lấy thông tin xác thực danh tính từ bất kỳ ví nào trên thiết bị Android hoặc web.
{
"requests" : [
{
"protocol": "openid4vp-v1-signed",
"data": {<signed_credential_request>} // This is an object, shouldn't be a string.
}
]
}
Yêu cầu mã hoá
client_metadata chứa khoá công khai mã hoá cho mỗi yêu cầu.
Bạn cần lưu trữ khoá riêng tư cho mỗi yêu cầu và sử dụng các khoá này để xác thực và cấp quyền cho mã thông báo mà bạn nhận được từ ứng dụng ví.
Tham số credential_request trong requestJson chứa các trường sau.
Thông tin xác thực cụ thể
{
"response_type": "vp_token",
"response_mode": "dc_api.jwt", // change this to dc_api if you want to demo with a non encrypted response.
"nonce": "1234",
"dcql_query": {
"credentials": [
{
"id": "cred1",
"format": "mso_mdoc",
"meta": {
"doctype_value": "org.iso.18013.5.1.mDL" // this is for mDL. Use com.google.wallet.idcard.1 for ID pass
},
"claims": [
{
"path": [
"org.iso.18013.5.1",
"family_name"
],
"intent_to_retain": false // set this to true if you are saving the value of the field
},
{
"path": [
"org.iso.18013.5.1",
"given_name"
],
"intent_to_retain": false
},
{
"path": [
"org.iso.18013.5.1",
"age_over_18"
],
"intent_to_retain": false
}
]
}
]
},
"client_metadata": {
"jwks": {
"keys": [ // sample request encryption key
{
"kty": "EC",
"crv": "P-256",
"x": "pDe667JupOe9pXc8xQyf_H03jsQu24r5qXI25x_n1Zs",
"y": "w-g0OrRBN7WFLX3zsngfCWD3zfor5-NLHxJPmzsSvqQ",
"use": "enc",
"kid" : "1", // This is required
"alg" : "ECDH-ES", // This is required
}
]
},
"vp_formats_supported": {
"mso_mdoc": {
"deviceauth_alg_values": [
-7
],
"isserauth_alg_values": [
-7
]
}
}
}
}
Mọi thông tin xác thực đủ điều kiện
Sau đây là ví dụ về yêu cầu cho cả mDL và thẻ giấy tờ tuỳ thân. Người dùng có thể tiếp tục với một trong hai thông tin xác thực này.
{
"response_type": "vp_token",
"response_mode": "dc_api.jwt", // change this to dc_api if you want to demo with a non encrypted response.
"nonce": "1234",
"dcql_query": {
"credentials": [
{
"id": "mdl-request",
"format": "mso_mdoc",
"meta": {
"doctype_value": "org.iso.18013.5.1.mDL"
},
"claims": [
{
"path": [
"org.iso.18013.5.1",
"family_name"
],
"intent_to_retain": false // set this to true if you are saving the value of the field
},
{
"path": [
"org.iso.18013.5.1",
"given_name"
],
"intent_to_retain": false
},
{
"path": [
"org.iso.18013.5.1",
"age_over_18"
],
"intent_to_retain": false
}
]
},
{ // Credential type 2
"id": "id_pass-request",
"format": "mso_mdoc",
"meta": {
"doctype_value": "com.google.wallet.idcard.1"
},
"claims": [
{
"path": [
"org.iso.18013.5.1",
"family_name"
],
"intent_to_retain": false // set this to true if you are saving the value of the field
},
{
"path": [
"org.iso.18013.5.1",
"given_name"
],
"intent_to_retain": false
},
{
"path": [
"org.iso.18013.5.1",
"age_over_18"
],
"intent_to_retain": false
}
]
}
]
credential_sets : [
{
"options": [
[ "mdl-request" ],
[ "id_pass-request" ]
]
}
]
},
"client_metadata": {
"jwks": {
"keys": [ // sample request encryption key
{
"kty": "EC",
"crv": "P-256",
"x": "pDe667JupOe9pXc8xQyf_H03jsQu24r5qXI25x_n1Zs",
"y": "w-g0OrRBN7WFLX3zsngfCWD3zfor5-NLHxJPmzsSvqQ",
"use": "enc",
"kid" : "1", // This is required
"alg" : "ECDH-ES", // This is required
}
]
},
"vp_formats_supported": {
"mso_mdoc": {
"deviceauth_alg_values": [
-7
],
"isserauth_alg_values": [
-7
]
}
}
}
}
Bạn có thể yêu cầu bất kỳ số lượng thuộc tính được hỗ trợ nào từ mọi thông tin xác thực danh tính được lưu trữ trong Google Wallet.
Yêu cầu đã ký
Yêu cầu đã ký (Yêu cầu cấp quyền được bảo mật bằng JWT) gói gọn yêu cầu bản trình bày có thể xác minh bên trong Mã thông báo web JSON (JWT) được ký bằng mật mã bằng cách sử dụng cơ sở hạ tầng PKI của bạn, đảm bảo tính toàn vẹn của yêu cầu và chứng minh danh tính của bạn với Google Wallet.
Điều kiện tiên quyết
Trước khi triển khai các thay đổi về mã cho yêu cầu đã ký, hãy đảm bảo bạn có:
- Khoá riêng tư: Bạn cần có khoá riêng tư (ví dụ: Đường cong elliptic
ES256) để ký yêu cầu được quản lý trong máy chủ của bạn. - Chứng chỉ: Bạn cần có chứng chỉ X.509 tiêu chuẩn bắt nguồn từ cặp khoá của bạn.
- Đăng ký: Đảm bảo chứng chỉ công khai của bạn đã được đăng ký với Google Wallet. Hãy liên hệ với nhóm hỗ trợ của chúng tôi tại
wallet-identity-rp-support@google.com
Logic xây dựng yêu cầu
Để xây dựng yêu cầu, bạn cần sử dụng khoá riêng tư và gói tải trọng trong JWS.
def construct_openid4vp_request(
doctypes: list[str],
requested_fields: list[dict],
nonce_base64: str,
jwe_encryption_public_jwk: jwk.JWK,
is_zkp_request: bool,
is_signed_request: bool,
state: dict,
origin: str
) -> dict:
# ... [Existing logic to build 'presentation_definition' and basic 'request_payload'] ...
# ------------------------------------------------------------------
# SIGNED REQUEST IMPLEMENTATION (JAR)
# ------------------------------------------------------------------
if is_signed_request:
try:
# 1. Load the Verifier's Certificate
# We must load the PEM string into a cryptography x509 object
verifier_cert_obj = x509.load_pem_x509_certificate(
CERTIFICATE.encode('utf-8'),
backend=default_backend()
)
# 2. Calculate Client ID (x509_hash)
# We calculate the SHA-256 hash of the DER-encoded certificate.
cert_der = verifier_cert_obj.public_bytes(serialization.Encoding.DER)
verifier_fingerprint_bytes = hashlib.sha256(cert_der).digest()
# Create a URL-safe Base64 hash (removing padding '=')
verifier_fingerprint_b64 = base64.urlsafe_b64encode(verifier_fingerprint_bytes).decode('utf-8').rstrip("=")
# Format the client_id as required by the spec
client_id = f'x509_hash:{verifier_fingerprint_b64}'
# 3. Update Request Payload with JAR specific fields
request_payload["client_id"] = client_id
# Explicitly set expected origins to prevent relay attacks
# Format for android origin: origin = android:apk-key-hash:<base64SHA256_ofAppSigningCert>
# Format for web origin: origin = <origin_url>
if origin:
request_payload["expected_origins"] = [origin]
# 4. Create Signed JWT (JWS)
# Load the signing private key
signing_key = jwk.JWK.from_pem(PRIVATE_KEY.encode('utf-8'))
# Initialize JWS with the JSON payload
jws_token = jws.JWS(json.dumps(request_payload).encode('utf-8'))
# Construct the JOSE Header
# 'x5c' (X.509 Certificate Chain) is critical: it allows the wallet
# to validate your key against the one registered in the console.
x5c_value = base64.b64encode(cert_der).decode('utf-8')
protected_header = {
"alg": "ES256", # Algorithm (e.g., ES256 or RS256)
"typ": "oauth-authz-req+jwt", # Standard type for JAR
"kid": "1", # Key ID
"x5c": [x5c_value] # Embed the certificate
}
# Sign the token
jws_token.add_signature(
key=signing_key,
alg=None,
protected=json_encode(protected_header)
)
# 5. Return the Request Object
# Instead of returning the raw JSON, we return the signed JWT string
# under the 'request' key.
return {"request": jws_token.serialize(compact=True)}
except Exception as e:
print(f"Error signing OpenID4VP request: {e}")
return None
# ... [Fallback for unsigned requests] ...
return request_payload
Kích hoạt API
Toàn bộ yêu cầu API phải được tạo ở phía máy chủ. Tuỳ thuộc vào nền tảng, bạn sẽ truyền JSON đã tạo vào các API gốc.
Trong ứng dụng (Android)
Để yêu cầu thông tin xác thực danh tính từ các ứng dụng Android, hãy làm theo các bước sau:
Cập nhật phần phụ thuộc
Trong build.gradle của dự án, hãy cập nhật các phần phụ thuộc để sử dụng Trình quản lý thông tin xác thực (beta):
dependencies {
implementation("androidx.credentials:credentials:1.5.0-beta01")
implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01")
}
Định cấu hình Trình quản lý thông tin xác thực
Để định cấu hình và khởi tạo đối tượng CredentialManager, hãy thêm logic tương tự
như sau:
// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = CredentialManager.create(context)
Yêu cầu thuộc tính danh tính
Thay vì chỉ định các tham số riêng lẻ cho yêu cầu danh tính, ứng dụng sẽ cung cấp tất cả các tham số này cùng nhau dưới dạng chuỗi JSON trong CredentialOption.
Trình quản lý thông tin xác thực sẽ truyền chuỗi JSON này cùng với các ví kỹ thuật số có sẵn mà không cần kiểm tra nội dung của chuỗi. Sau đó, mỗi ví sẽ chịu trách nhiệm:
- Phân tích cú pháp chuỗi JSON để hiểu yêu cầu danh tính.
- Xác định thông tin xác thực nào trong số thông tin xác thực được lưu trữ (nếu có) đáp ứng yêu cầu.
Các đối tác nên tạo yêu cầu trên máy chủ ngay cả đối với việc tích hợp ứng dụng Android.
Bạn sẽ sử dụng requestJson từ Định dạng yêu cầu
làm request trong lệnh gọi hàm GetDigitalCredentialOption().
// 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)
}
}
Xử lý phản hồi thông tin xác thực
Sau khi nhận được phản hồi từ ví, bạn sẽ xác minh xem phản hồi đó có thành công và chứa phản hồi credentialJson hay không.
// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
val credential = result.credential
when (credential) {
is DigitalCredential -> {
val responseJson = credential.credentialJson
validateResponseOnServer(responseJson) // make a server call to validate the response
}
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.
}
else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
}
}
Phản hồi credentialJson chứa identityToken (JWT) được mã hoá, do W3C xác định. Ứng dụng Wallet chịu trách nhiệm tạo phản hồi này.
Ví dụ:
{
"protocol" : "openid4vp-v1-signed",
"data" : {
<encrpted_response>
}
}
Bạn sẽ truyền phản hồi này trở lại máy chủ để xác thực tính xác thực của phản hồi. Bạn có thể tìm thấy các bước để xác thực phản hồi thông tin xác thực
Web
Để yêu cầu Thông tin xác thực danh tính bằng API Thông tin xác thực kỹ thuật số trên Chrome hoặc các trình duyệt được hỗ trợ khác, hãy đưa ra yêu cầu sau.
const credentialResponse = await navigator.credentials.get({
digital : {
requests : [
{
protocol: "openid4vp-v1-signed",
data: {<credential_request>} // This is an object, shouldn't be a string.
}
]
}
})
Gửi phản hồi từ API này trở lại máy chủ của bạn để xác thực thông tin xác thực
Xác thực phản hồi
Sau khi ví trả về identityToken (JWT) được mã hoá, bạn phải thực hiện quy trình xác thực phía máy chủ nghiêm ngặt trước khi tin tưởng dữ liệu.
Giải mã phản hồi
Sử dụng khoá riêng tư tương ứng với khoá công khai được gửi trong client_metadata của yêu cầu để giải mã JWE. Thao tác này sẽ tạo ra vp_token.
Ví dụ về Python:
from jwcrypto import jwe, jwk
# Retrieve the Private Key from Datastore
reader_private_jwk = jwk.JWK.from_json(jwe_private_key_json_str)
# Save public key thumbprint for session transcript
encryption_public_jwk_thumbprint = reader_private_jwk.thumbprint()
# Decrypt the JWE encrypted response from Google Wallet
jwe_object = jwe.JWE()
jwe_object.deserialize(encrypted_jwe_response_from_wallet)
jwe_object.decrypt(reader_private_jwk)
decrypted_payload_bytes = jwe_object.payload
decrypted_data = json.loads(decrypted_payload_bytes)
decrypted_data sẽ tạo ra JSON vp_token chứa thông tin xác thực
{
"vp_token":
{
"cred1": ["<base64UrlNoPadding_encoded_credential>"] // This applies to OpenID4VP 1.0 spec.
}
}
Tạo bản chép lời phiên
Bước tiếp theo là tạo SessionTranscript từ ISO/IEC 18013-5:2021 với cấu trúc Bàn giao dành riêng cho Android hoặc Web:
SessionTranscript = [ null, // DeviceEngagementBytes not available null, // EReaderKeyBytes not available [ "OpenID4VPDCAPIHandover", AndroidHandoverDataBytes // BrowserHandoverDataBytes for Web ] ]Đối với cả quá trình bàn giao trên Android và web, bạn cần sử dụng cùng một giá trị nonce mà bạn đã dùng để tạo
credential_request.Bàn giao trên Android
AndroidHandoverData = [ origin, // "android:apk-key-hash:<base64SHA256_ofAppSigningCert>", nonce, // nonce that was used to generate credential request, encryption_public_jwk_thumbprint, // Encryption public key (JWK) Thumbprint ] AndroidHandoverDataBytes = hashlib.sha256(cbor2.dumps(AndroidHandoverData)).digest()
Bàn giao trên trình duyệt
BrowserHandoverData =[ origin, // Origin URL nonce, // nonce that was used to generate credential request encryption_public_jwk_thumbprint, // Encryption public key (JWK) Thumbprint ] BrowserHandoverDataBytes = hashlib.sha256(cbor2.dumps(BrowserHandoverData)).digest()
Khi sử dụng
SessionTranscript, Phản hồi thiết bị phải được xác thực theo điều khoản 9 của ISO/IEC 18013-5:2021. Điều này bao gồm một số bước, chẳng hạn như:Kiểm tra Chứng chỉ của tổ chức phát hành tiểu bang. Tham khảo chứng chỉ IACA của tổ chức phát hành được hỗ trợ.
Xác minh chữ ký MSO (Mục 9.1.2 của 18013-5)
Tính toán và kiểm tra
ValueDigestscho các Phần tử dữ liệu (Mục 9.1.2 của 18013-5)Xác minh chữ ký
deviceSignature(Mục 9.1.3 của 18013-5)
{
"version": "1.0",
"documents": [
{
"docType": "org.iso.18013.5.1.mDL",
"issuerSigned": {
"nameSpaces": {...}, // contains data elements
"issuerAuth": [...] // COSE_Sign1 w/ issuer PK, mso + sig
},
"deviceSigned": {
"nameSpaces": 24(<< {} >>), // empty
"deviceAuth": {
"deviceSignature": [...] // COSE_Sign1 w/ device signature
}
}
}
],
"status": 0
}
Xác minh độ tuổi đảm bảo quyền riêng tư (ZKP)
Để hỗ trợ Bằng chứng không tiết lộ thông tin (ví dụ: xác minh rằng người dùng trên 18 tuổi mà không cần xem ngày sinh chính xác của họ), hãy thay đổi định dạng yêu cầu thành mso_mdoc_zk và cung cấp cấu hình zk_system_type bắt buộc.
Để biết thông tin tổng quan về ZKP và các tính năng của ZKP, hãy xem Câu hỏi thường gặp.
...
"dcql_query": {
"credentials": [{
"id": "cred1",
"format": "mso_mdoc_zk",
"meta": {
"doctype_value": "org.iso.18013.5.1.mDL"
"zk_system_type": [
{
"system": "longfellow-libzk-v1",
"circuit_hash": "f88a39e561ec0be02bb3dfe38fb609ad154e98decbbe632887d850fc612fea6f", // This will differ if you need more than 1 attribute.
"num_attributes": 1, // number of attributes (in claims) this has can support
"version": 5,
"block_enc_hash": 4096,
"block_enc_sig": 2945,
}
{
"system": "longfellow-libzk-v1",
"circuit_hash": "137e5a75ce72735a37c8a72da1a8a0a5df8d13365c2ae3d2c2bd6a0e7197c7c6", // This will differ if you need more than 1 attribute.
"num_attributes": 1, // number of attributes (in claims) this has can support
"version": 6,
"block_enc_hash": 4096,
"block_enc_sig": 2945,
}
],
"verifier_message": "challenge"
},
"claims": [{
...
"client_metadata": {
"jwks": {
"keys": [ // sample request encryption key
{
...
Bạn sẽ nhận được bằng chứng không tiết lộ thông tin được mã hoá từ ví. Bạn có thể xác thực bằng chứng này dựa trên chứng chỉ IACA của tổ chức phát hành bằng thư viện longfellow-zk của Google.
verifier-service chứa một máy chủ dựa trên Docker sẵn sàng triển khai, cho phép bạn xác thực phản hồi dựa trên một số chứng chỉ IACA của tổ chức phát hành.
Bạn có thể sửa đổi certs.pem để quản lý các chứng chỉ của tổ chức phát hành IACA mà bạn muốn tin cậy.
Tài nguyên và hỗ trợ
- Câu hỏi thường gặp: Để biết các câu hỏi thường gặp về việc tích hợp kỹ thuật, hãy xem Câu hỏi thường gặp về thông tin xác thực và danh tính kỹ thuật số.
- Triển khai tham chiếu: Hãy xem Triển khai tham chiếu về trình xác minh danh tính của chúng tôi trên GitHub.
- Trang web kiểm thử: Hãy thử quy trình đầu cuối tại verifier.multipaz.org.
- Thông số kỹ thuật OpenID4VP: Hãy xem thông số kỹ thuật cho openID4VP.
- Hỗ trợ: Để được hỗ trợ gỡ lỗi hoặc có câu hỏi trong quá trình tích hợp, hãy liên hệ với
wallet-identity-rp-support@google.com.