Akceptacja cyfrowych dokumentów tożsamości online

Z tego przewodnika dowiesz się, jak podmioty ufające mogą technicznie zintegrować interfejs Digital Credentials API, aby żądać i weryfikować mobilne prawa jazdy (mDL) i karty tożsamości z Portfela Google w aplikacjach na Androida i w internecie.

(w języku angielskim).

Proces rejestracji i wymagania wstępne

Zanim opublikujesz aplikację w wersji produkcyjnej, musisz formalnie zarejestrować ją w Google jako podmiot ufający.

  1. Testowanie w piaskownicy: możesz od razu rozpocząć programowanie, korzystając z naszego środowiska piaskownicytworząc identyfikator testowy. Akceptowanie warunków korzystania z usługi nie jest wymagane w przypadku testowania.
  2. Prześlij formularz zgłoszenia: wypełnij formularz rejestracji w programie Revenue Platform. Wprowadzenie zwykle zajmuje 3–5 dni roboczych. Nazwa i logo usługi będą wyświetlane na ekranie zgody widocznym dla użytkowników, aby ułatwić im rozpoznanie podmiotu, który prosi o ich dane.
  3. Zaakceptuj Warunki korzystania z usługi: zanim zaczniesz nadawać na żywo, musisz podpisać Warunki korzystania z usługi.

Obsługiwane formaty i możliwości

Portfel Google obsługuje cyfrowe dokumenty tożsamości oparte na ISO mdoc.

Formatowanie żądania

Aby poprosić o dane uwierzytelniające z dowolnego portfela, musisz sformatować żądanie za pomocą OpenID4VP. Możesz poprosić o konkretne lub wiele rodzajów danych logowania w jednym obiekcie dcql_query.

Przykład żądania JSON

Oto przykładowe żądanie mdoc requestJson dotyczące uzyskania dokumentów tożsamości z dowolnego portfela na urządzeniu z Androidem lub w internecie.

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

Prośba o szyfrowanie

client_metadata zawiera klucz publiczny szyfrowania dla każdego żądania. Musisz przechowywać klucze prywatne dla każdego żądania i używać ich do uwierzytelniania i autoryzowania tokena otrzymanego z aplikacji portfela.

Parametr credential_requestrequestJson zawiera te pola:

Określone dane logowania

{
  "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
        ]
      }
    }
  }
}

Dowolne kwalifikujące się dane logowania

Oto przykładowe żądanie dotyczące zarówno mDL, jak i dokumentu tożsamości. Użytkownik może wybrać jedną z tych opcji.

{
  "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
        ]
      }
    }
  }
}

Możesz poprosić o dowolną liczbę obsługiwanych atrybutów z dowolnego dokumentu tożsamości przechowywanego w Portfelu Google.

Podpisane żądania

Podpisane żądania (żądania autoryzacji zabezpieczone tokenem JWT) zawierają żądanie prezentacji weryfikowalnej w postaci podpisanego kryptograficznie tokena sieciowego JSON (JWT) z użyciem infrastruktury PKI. Zapewnia to integralność żądania i potwierdza Twoją tożsamość w Portfelu Google.

Wymagania wstępne

Przed wprowadzeniem zmian w kodzie w przypadku podpisanej prośby upewnij się, że:

  • Klucz prywatny: do podpisania żądania potrzebujesz klucza prywatnego (np. krzywej eliptycznej ES256), którym zarządzasz na serwerze.
  • Certyfikat: potrzebujesz standardowego certyfikatu X.509 pochodzącego z pary kluczy.
  • Rejestracja: upewnij się, że Twój certyfikat publiczny jest zarejestrowany w Portfelu Google. Skontaktuj się z naszym zespołem pomocy pod numerem wallet-identity-rp-support@google.com

Logika tworzenia prośby

Aby utworzyć żądanie, musisz użyć klucza prywatnego i zawinąć ładunek w 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

Wywoływanie interfejsu API

Całe żądanie do interfejsu API powinno być generowane po stronie serwera. W zależności od platformy wygenerowany plik JSON zostanie przekazany do natywnych interfejsów API.

W aplikacji (Android)

Aby poprosić o dane logowania w aplikacjach na Androida:

Aktualizowanie zależności

W pliku build.gradle projektu zaktualizuj zależności, aby używać usługi Credential Manager (wersja beta):

dependencies {
    implementation("androidx.credentials:credentials:1.5.0-beta01")
    implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01")
}

Konfigurowanie Menedżera danych logowania

Aby skonfigurować i zainicjować obiekt CredentialManager, dodaj logikę podobną do tej:

// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = CredentialManager.create(context)

Żądanie atrybutów tożsamości

Zamiast określać poszczególne parametry żądań dotyczących tożsamości, aplikacja podaje je wszystkie razem jako ciąg JSON w parametrze CredentialOption. Credential Manager przekazuje ten ciąg znaków JSON do dostępnych portfeli cyfrowych bez sprawdzania jego zawartości. Każdy portfel jest odpowiedzialny za:<ul><li>parsowanie ciągu JSON w celu zrozumienia żądania tożsamości; – określanie, które z przechowywanych przez nią danych logowania spełniają wymagania żądania;

Zalecamy partnerom tworzenie żądań na serwerze nawet w przypadku integracji z aplikacjami na Androida.

Użyj requestJson z sekcji Format żądania jako request w wywołaniu funkcji 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)
    }
}

Obsługa odpowiedzi dotyczącej danych logowania

Gdy otrzymasz odpowiedź z portfela, sprawdź, czy jest ona prawidłowa i zawiera odpowiedź 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}")
    }
}

Odpowiedź credentialJson zawiera zaszyfrowany identityToken (JWT) zdefiniowany przez W3C. Za przygotowanie tej odpowiedzi odpowiada aplikacja Portfel.

Przykład:

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

Przekaż tę odpowiedź z powrotem na serwer, aby potwierdzić jej autentyczność. Instrukcje weryfikacji odpowiedzi dotyczącej danych logowania

Sieć

Aby poprosić o dane logowania za pomocą interfejsu Digital Credentials API w Chrome lub innych obsługiwanych przeglądarkach, wyślij to żądanie.

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

Wyślij odpowiedź z tego interfejsu API z powrotem na serwer, aby zweryfikować odpowiedź dotyczącą danych logowania.

Weryfikacja odpowiedzi

Gdy portfel zwróci zaszyfrowany token identityToken (JWT), musisz przeprowadzić ścisłą weryfikację po stronie serwera, zanim zaufasz danym.

Odszyfrowywanie odpowiedzi

Aby odszyfrować token JWE, użyj klucza prywatnego odpowiadającego kluczowi publicznemu wysłanemu w żądaniu client_metadata. Daje to vp_token.

Przykład w Pythonie:

  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 spowoduje utworzenie pliku vp_token JSON zawierającego dane logowania.

  {
    "vp_token":
    {
      "cred1": ["<base64UrlNoPadding_encoded_credential>"] // This applies to OpenID4VP 1.0 spec.
    }
  }
  1. Tworzenie transkrypcji sesji

    Następnym krokiem jest utworzenie SessionTranscript zgodnie z ISO/IEC 18013-5:2021 z strukturą przekazywania specyficzną dla Androida lub internetu:

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

    W przypadku przekazywania w Androidzie i w internecie musisz użyć tej samej liczby jednorazowej, której użyto do wygenerowania credential_request.

    Przekazywanie połączeń na Androidzie

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

    Przekazywanie przeglądarki

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

    Za pomocą SessionTranscript należy zweryfikować odpowiedź urządzenia zgodnie z klauzulą 9 normy ISO/IEC 18013-5:2021. Obejmuje to kilka kroków, takich jak:

  2. Sprawdź certyfikat wydany przez stan. Zapoznaj się z certyfikatami IACA obsługiwanego wydawcy.

  3. Weryfikacja podpisu MSO (18013-5 Section 9.1.2)

  4. Oblicz i sprawdź ValueDigests dla elementów danych (18013-5, sekcja 9.1.2)

  5. Weryfikacja podpisu deviceSignature (18013-5 Section 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
}

Weryfikacja wieku z zachowaniem prywatności (ZKP)

Aby obsługiwać dowody z zerową wiedzą (np. weryfikować, czy użytkownik ma ukończone 18 lat, bez sprawdzania dokładnej daty urodzenia), zmień format żądania na mso_mdoc_zk i podaj wymaganą konfigurację 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
            {
              ...

Portfel zwróci zaszyfrowany dowód zerowej wiedzy. Możesz zweryfikować ten dowód na podstawie certyfikatów IACA wydawców za pomocą biblioteki longfellow-zk Google.

verifier-service zawiera gotowy do wdrożenia serwer oparty na Dockerze, który umożliwia weryfikację odpowiedzi na podstawie niektórych certyfikatów IACA wystawcy.

Możesz zmodyfikować plik certs.pem, aby zarządzać certyfikatami wystawcy IACA, którym chcesz zaufać.

Materiały i pomoc

  • Implementacja referencyjna: zapoznaj się z naszą implementacją referencyjną weryfikatorów tożsamości w GitHubie.
  • Testowanie witryny: wypróbuj cały proces na stronie verifier.multipaz.org.
  • Specyfikacja OpenID4VP: zapoznaj się ze specyfikacją techniczną openID4VP.
  • Pomoc: jeśli podczas integracji potrzebujesz pomocy w rozwiązywaniu problemów lub masz pytania, skontaktuj się z wallet-identity-rp-support@google.com.