本指南說明信賴方 (RP) 如何從技術層面整合 Digital Credentials API，以便在 Android 應用程式和網頁中，向 Google 錢包要求及驗證行動駕照 (mDL) 和身分證件。
註冊程序與必要條件
在正式版中發布前，您必須向 Google 正式註冊您的 Relying Party 應用程式。
- 在沙箱中測試：您可以使用我們的沙箱環境和建立測試 ID，立即開始開發。 測試時不必接受《服務條款》。
- 提交登記表單：填寫 RP 新手上路表單。 通常需要 3 到 5 個工作天。系統會在使用者看到的同意畫面上顯示產品名稱和標誌，協助使用者識別要求存取資料的對象。
- 接受《服務條款》：你必須先簽署《服務條款》，才能開始直播。
支援的格式和功能
Google 錢包支援以 ISO mdoc 為基礎的數位身分證件。
- 支援的憑證：你可以查看支援的憑證和屬性。
- 支援的通訊協定： OpenID4VP (1.0 版)。
- 最低 Android SDK：Android 9 以上版本 (API 層級 28)。
- 瀏覽器支援：如需支援 Digital Credentials API 的瀏覽器完整清單，請參閱生態系統支援頁面。
格式化要求
如要從任何錢包要求憑證，必須使用 OpenID4VP 格式提出要求。您可以在單一 dcql_query 物件中要求特定憑證或多個憑證。
JSON 要求範例
以下是 mdoc requestJson 要求範例，可從 Android 裝置或網頁上的任何錢包取得身分憑證。
{
"requests" : [
{
"protocol": "openid4vp-v1-signed",
"data": {<signed_credential_request>} // This is an object, shouldn't be a string.
}
]
}
要求加密
client_metadata 包含每個要求的加密公開金鑰。
您需要儲存每個要求的私密金鑰，並使用這些金鑰驗證及授權從錢包應用程式收到的權杖。
requestJson 中的 credential_request 參數包含下列欄位。
特定憑證
{
"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
]
}
}
}
}
任何符合資格的憑證
以下是 mDL 和身分證件的範例要求。使用者可以選擇其中一種方式繼續操作。
{
"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
]
}
}
}
}
您可以從儲存在 Google 錢包中的任何身分證件，要求任意數量的支援屬性。
已簽署的要求
已簽署要求 (JWT 安全授權要求) 會使用 PKI 基礎架構，將可驗證的呈現要求封裝在經過加密簽署的 JSON Web Token (JWT) 中，確保要求完整性，並向 Google 錢包證明您的身分。
必要條件
在為已簽署的要求實作程式碼變更前，請確認您已完成下列事項：
- 私密金鑰：您需要私密金鑰 (例如橢圓曲線
ES256) 才能簽署伺服器管理的要求。 - 憑證：您需要從金鑰組衍生的標準 X.509 憑證。
- 註冊：請確認公開憑證已向 Google 錢包註冊。請致電
wallet-identity-rp-support@google.com與支援團隊聯絡
要求建構邏輯
如要建構要求，您必須使用私密金鑰，並將酬載包裝在 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
觸發 API
整個 API 請求應在伺服器端產生。視平台而定，您會將產生的 JSON 傳遞至原生 API。
應用程式內 (Android)
如要從 Android 應用程式要求身分憑證，請按照下列步驟操作：
更新依附元件
在專案的 build.gradle 檔案中更新依附元件，以便使用 Credential Manager (Beta 版)：
dependencies {
implementation("androidx.credentials:credentials:1.5.0-beta01")
implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01")
}
設定 Credential Manager
如要設定及初始化 CredentialManager 物件，請新增類似以下的邏輯：
// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = CredentialManager.create(context)
要求身分屬性
應用程式會將身分要求的所有參數一併提供為 CredentialOption 中的 JSON 字串，而非個別指定。憑證管理工具會將這個 JSON 字串傳遞至可用的數位錢包，但不會檢查內容。每個錢包隨後會負責：
- 剖析 JSON 字串，瞭解身分識別要求。
- 判斷儲存的憑證 (如有) 是否符合要求。
即使是 Android 應用程式整合，我們也建議合作夥伴在伺服器上建立請求。
您會在 GetDigitalCredentialOption() 函式呼叫中，使用「要求格式」的 requestJson 做為 request。
// 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)
}
}
處理憑證回應
錢包傳回回應後，請確認回應是否成功，且包含 credentialJson 回應。
// 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}")
}
}
credentialJson 回應會包含 W3C 定義的加密 identityToken (JWT)。Google 錢包應用程式會負責製作這則回覆。
範例：
{
"protocol" : "openid4vp-v1-signed",
"data" : {
<encrpted_response>
}
}
您會將這項回應傳回伺服器，驗證其真實性。您可以參閱這篇文章，瞭解如何驗證憑證回應
網頁
如要在 Chrome 或其他支援的瀏覽器上，使用 Digital Credentials API 要求身分憑證，請發出下列要求。
const credentialResponse = await navigator.credentials.get({
digital : {
requests : [
{
protocol: "openid4vp-v1-signed",
data: {<credential_request>} // This is an object, shouldn't be a string.
}
]
}
})
將此 API 的回應傳回伺服器，驗證憑證回應
驗證回覆
錢包傳回加密的 identityToken (JWT) 後，您必須先執行嚴格的伺服器端驗證，才能信任該資料。
將回覆解密
使用與要求 client_metadata 中傳送的公開金鑰對應的私密金鑰，解密 JWE。這會產生 vp_token。
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 會產生包含憑證的 vp_token JSON
{
"vp_token":
{
"cred1": ["<base64UrlNoPadding_encoded_credential>"] // This applies to OpenID4VP 1.0 spec.
}
}
建立工作階段轉錄稿
下一個步驟是從 ISO/IEC 18013-5:2021 建立 SessionTranscript，並使用 Android 或網頁專屬的交接結構：
SessionTranscript = [ null, // DeviceEngagementBytes not available null, // EReaderKeyBytes not available [ "OpenID4VPDCAPIHandover", AndroidHandoverDataBytes // BrowserHandoverDataBytes for Web ] ]無論是 Android 或網頁移交，您都必須使用產生
credential_request時使用的相同隨機值。Android Handover
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()
瀏覽器交接
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()
使用
SessionTranscript時，必須根據 ISO/IEC 18013-5:2021 第 9 條款驗證裝置回應。包括下列步驟：檢查州政府發行證書。請參閱支援的發卡機構 IACA 憑證。
驗證 MSO 簽章 (18013-5 第 9.1.2 節)
計算及檢查
ValueDigests資料元素 (18013-5 第 9.1.2 節)驗證
deviceSignature簽章 (18013-5 第 9.1.3 節)
{
"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
}
隱私權保護年齡驗證 (ZKP)
如要支援零知識證明 (例如驗證使用者是否年滿 18 歲，但不顯示確切生日)，請將要求格式變更為 mso_mdoc_zk，並提供必要的 zk_system_type 設定。
...
"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
{
...
錢包會回傳加密的零知識證明。您可以使用 Google 的 longfellow-zk 程式庫，根據發行者的 IACA 憑證驗證這項證明。
驗證器服務包含可供部署的 Docker 型伺服器，可讓您根據特定簽發者 IACA 憑證驗證回應。
您可以修改 certs.pem，管理要信任的 IACA 簽發者憑證。
資源與支援
- 實作參考資料：請參閱 GitHub 上的身分驗證者實作參考資料。
- 測試網站：在 verifier.multipaz.org 嘗試端對端流程。
- OpenID4VP 規格：請參閱 openID4VP 的技術規格。
- 支援：如需整合期間的偵錯協助或有任何疑問，請與
wallet-identity-rp-support@google.com聯絡。