デジタル認証情報のオンラインでの受領

デジタル ID は、アプリ内フローとウェブフローの両方で受け付けられます。Google ウォレットの認証情報を受け入れるには、次の操作を行う必要があります。

  1. 提供された手順に沿って、アプリまたはウェブを使用して統合します。
  2. テスト ID を使用して、Google ウォレットのサンドボックスでフローをテストします。
  3. リリースするには、こちらのフォームに記入してアクセスをリクエストし、Google ウォレットの認証情報の利用規約に同意してください。各事業体について記入する必要があります。フォームにご記入いただくと、担当チームからご連絡いたします。
  4. ご不明な点がございましたら、wallet-identity-rp-support@google.comまでお問い合わせください。

サポートされている認証情報の形式

デジタル ID ドキュメントのデータ形式を定義する標準案がいくつか存在し、そのうち 2 つが業界で大きな支持を得ています。

  1. mdocs - ISO によって定義されます。
  2. w3c 検証可能な認証情報 - w3c によって定義されます。

Android 認証情報マネージャーは両方の形式をサポートしていますが、現時点では Google ウォレットは mdoc ベースのデジタル ID のみをサポートしています。

サポートされている認証情報

Google ウォレットは 2 種類の認証情報に対応しています。

  1. モバイル運転免許証(mDL)
  2. ID パス

フローで 1 つのパラメータを変更するだけで、どちらの認証情報もリクエストできます。

ユーザー エクスペリエンス

このセクションでは、推奨されるオンライン プレゼンテーションのフローについて説明します。このフローは、アルコール配送アプリに年齢を提示する流れを示していますが、ウェブや他のタイプの提示でも UX は同様です。

アプリまたはウェブサイトで年齢確認を求められる ユーザーに利用可能な資格情報が表示される Google ウォレットに確認ページが表示される ユーザーが認証して共有を確認する アプリまたはウェブサイトに送信されるデータ
アプリまたはウェブサイトで年齢確認を求められる ユーザーに利用可能な資格情報が表示される Google ウォレットに確認ページが表示される ユーザーが認証して共有を確認する アプリまたはウェブサイトに送信されるデータ

重要な注意事項

  1. アプリやウェブサイトは、API へのエントリ ポイントの作成方法を柔軟に選択できます。ステップ 1 で説明したように、API を通じて Google ウォレット以外のオプションも利用できるようになることが見込まれるため、[デジタル ID で確認] などの汎用的なボタンを表示することをおすすめします。
  2. ステップ 2 の選択画面は Android によってレンダリングされます。利用可能な認証情報は、各ウォレットが提供する登録ロジックと、証明書利用者が送信するリクエストとの一致によって決まります。
  3. ステップ 3 は Google ウォレットによってレンダリングされます。この画面には、デベロッパーが提供した名前、ロゴ、プライバシー ポリシーが表示されます。

デジタル ID フローを追加する

ユーザーが認証情報を持っていない場合は、[デジタル ID で確認] ボタンの横に、Google ウォレットへのディープリンクを表示して、ユーザーがデジタル ID を追加できるようにすることをおすすめします。

アプリまたはウェブサイトで年齢確認を求められる デジタル ID を取得するために Google ウォレットに移動するユーザー
アプリまたはウェブサイトで年齢確認を求められる デジタル ID を取得するために Google ウォレットに移動するユーザー

利用可能なデジタル ID がない

ユーザーがデジタル ID を持っていない状態で [デジタル ID で確認] オプションを選択すると、このエラー メッセージが表示されます。

アプリまたはウェブサイトで年齢確認を求められる デジタル ID をお持ちでないユーザーにエラーが表示される
アプリまたはウェブサイトで年齢確認を求められる デジタル ID をお持ちでないユーザーにエラーが表示される

ユーザーのプライバシーを保護するため、ユーザーが利用可能なデジタル ID を持っているかどうかをサイレントに学習する機能は API でサポートされていません。そのため、図のようにオンボーディング リンク オプションを含めることをおすすめします。

ウォレットから ID 認証情報をリクエストするためのリクエスト フォーマット

Android デバイスまたはウェブ上の任意のウォレットから ID 認証情報を取得するための mdoc requestJson リクエストのサンプルを次に示します。

{
      "requests" : [
        {
          "protocol": "openid4vp-v1-unsigned", // openid4vp-v1-signed for signed request.
          "data": {<credential_request>} // This is an object, shouldn't be a string.
        }
      ]
}

リクエストの暗号化

client_metadata には、リクエストごとの暗号化公開鍵が含まれます。リクエストごとに秘密鍵を保存し、それを使用してウォレット アプリから受け取ったトークンを認証して承認する必要があります。

requestJsoncredential_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 と ID パスの両方のリクエストの例を次に示します。どちらの方法でも手続きを進めることができます。

{
  "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 ウォレットに保存されている ID 認証情報から、任意の数のサポートされている属性をリクエストできます。

署名付きリクエスト

セキュリティを強化し、認証リクエストの完全性を確保するには、署名付きリクエスト(JWT で保護された認可リクエスト、JAR とも呼ばれます)を実装する必要があります。詳しくは、openID4VP のドキュメントをご覧ください。

パラメータが未加工の JSON として送信される署名なしリクエストとは異なり、署名付きリクエストでは、検証可能なプレゼンテーション リクエストが暗号で署名された JSON ウェブトークン(JWT)内にカプセル化されます。これには、主に 2 つのメリットがあります。

  1. 完全性: リクエストが改ざんされていないことを確認します。
  2. 代替認証メカニズム(x509 PKI): Google ウォレットに、リクエストが Google ウォレットに登録されている特定の公開鍵を所有する検証ツールから送信されたことを証明します。

前提条件

署名付きリクエストのコード変更を実装する前に、次のことを確認してください。

  • 秘密鍵: 秘密鍵(楕円曲線 ES256 または RSA)を使用してリクエストに署名します。この鍵はサーバーで管理されます。
  • 証明書: 鍵ペアから派生した標準の 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
            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

アプリ内

Android アプリから ID 認証情報をリクエストする手順は次のとおりです。

依存関係を更新する

プロジェクトの build.gradle で、認証情報マネージャー(ベータ版)を使用するように依存関係を更新します。

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)

ID 属性をリクエストする

ID リクエストの個々のパラメータを指定する代わりに、アプリは CredentialOption 内の JSON 文字列としてすべてのパラメータをまとめて提供します。Credential Manager は、この JSON 文字列の内容を調べずに、利用可能なデジタル ウォレットに渡します。各ウォレットは、次の処理を行います。 - JSON 文字列を解析して、ID リクエストを理解します。- 保存されている認証情報のうち、リクエストを満たすものを判断する。

Android アプリの統合の場合でも、サーバーでリクエストを作成することをおすすめします。

リクエスト形式requestJsonGetDigitalCredentialOption() 関数呼び出しの 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)が含まれます。このレスポンスの作成はウォレット アプリが行います。

例:

{
  "protocol" : "openid4vp-v1-unsigned",
  "data" : {
    <encrpted_response>
  }
}

このレスポンスをサーバーに渡して、正当性を検証します。認証情報のレスポンスを検証する手順をご覧ください。

ウェブ

Chrome またはその他のサポートされているブラウザで Digital Credentials API を使用して Identity Credentials をリクエストするには、次のリクエストを行います。

const credentialResponse = await navigator.credentials.get({
          digital : {
          requests : [
            {
              protocol: "openid4vp-v1-unsigned",
              data: {<credential_request>} // This is an object, shouldn't be a string.
            }
          ]
        }
      })

この API からのレスポンスをサーバーに送り返して、認証情報のレスポンスを検証します。

認証情報のレスポンスを検証する手順

アプリまたはウェブサイトから暗号化された identityToken を受け取ったら、レスポンスを信頼する前に複数の検証を行う必要があります。

  1. 秘密鍵を使用してレスポンスを復号する

    まず、保存した秘密鍵を使用してトークンを復号し、レスポンス JSON を取得します。

    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.
      }
    }
    
  2. セッションの文字起こしを作成する

    次のステップでは、Android またはウェブ固有のハンドオーバー構造を使用して、ISO/IEC 18013-5:2021 から SessionTranscript を作成します。

    SessionTranscript = [
      null,                // DeviceEngagementBytes not available
      null,                // EReaderKeyBytes not available
      [
        "OpenID4VPDCAPIHandover",
        AndroidHandoverDataBytes   // BrowserHandoverDataBytes for Web
      ]
    ]
    

    Android とウェブの両方のハンドオーバーで、credential_request の生成に使用したのと同じ nonce を使用する必要があります。

    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()
        

    ブラウザの引き渡し

        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 に従って DeviceResponse を検証する必要があります。これには、次のような複数のステップが含まれます。

  3. State Issuer Cert を確認します。サポートされている発行者の IACA 証明書を参照してください。

  4. MSO 署名を検証する(18013-5 セクション 9.1.2)

  5. データ要素の ValueDigest を計算して確認する(18013-5 セクション 9.1.2)

  6. 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
}

ソリューションを構築する

ソリューションを構築するには、GitHub の Identity Verifiers リファレンス実装を参照してください。

ゼロ知識証明(ZKP)に基づく確認

ゼロ知識証明(ZKP)は、個人(証明者)が、基盤となる実際のデータを明らかにすることなく、特定の身元情報を持っていることや特定の基準を満たしていること(18 歳以上である、有効な資格情報を保持しているなど)を検証者に対して証明できる暗号手法です。つまり、機密情報を非公開のまま、自分の身元に関するステートメントの真実性を確認する方法です。

ID データの直接共有に依存するデジタル ID システムでは、ユーザーが過剰な個人情報を共有する必要があることが多く、データ侵害や ID 盗用のリスクが高まります。ZKP はパラダイム シフトをもたらし、最小限の開示で検証を可能にします。

デジタル ID における ZKP の主なコンセプト:

  • 証明者: 自分の身元の一面を証明しようとしている個人。
  • 検証ツール: ID 属性の証明をリクエストするエンティティ。
  • 証明: 秘密情報を開示することなく、証明者が検証者に主張の真実性を納得させることを可能にする暗号プロトコル。

ゼロ知識証明の主な特性:

  • 完全性: ステートメントが true で、証明者と検証者の両方が正直であれば、検証者は納得します。
  • 健全性: ステートメントが偽の場合、不正な証明者は、それが真であると正直な検証者を説得できません(非常に高い確率で)。
  • ゼロ知識: 検証者は、ステートメントが真実であるという事実以外は何も学習しません。証明者の身元に関する実際のデータは公開されません。

Google ウォレットからゼロ知識証明を取得するには、リクエストの形式を 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 証明書に対して検証できます。

verifier-service には、特定の発行者 IACA 証明書に対してレスポンスを検証できる、デプロイ準備完了の Docker ベースのサーバーが含まれています。

certs.pem を変更して、信頼する IACA 発行者証明書を管理できます。

詳細については、サポート メールにお問い合わせください。 wallet-identity-rp-support@google.com