Etapa 3: integrar como uma parte confiável

Este guia explica como as partes confiáveis (RPs) diretas (comerciantes, empresas e desenvolvedores de apps) integram a API Digital Credentials para solicitar e validar credenciais de identidade digital em apps Android e na Web.

Como funciona a integração com a parte confiável

Cada integração de parte confiável segue quatro etapas. As etapas A e C são executadas no seu servidor. A etapa B é executada no app Android ou no navegador. Selecione qualquer etapa para acessar os detalhes de implementação:

Crie e teste no sandbox antes de solicitar credenciais de produção

Ao implementar as etapas de A a D, use os recursos de sandbox pré-confiáveis do Google para criar e testar imediatamente:

Assinatura de solicitação

Assine as solicitações do OpenID4VP usando as chaves de teste e os metadados do sandbox do Google.

Testar credencial

Teste em um dispositivo Android no modo sandbox com um passe de identificação de teste da Utopia.

Validação da resposta

Valide issuerAuth em relação ao certificado do sandbox da Utopia.

Sequência completa entre seu servidor de back-end, app cliente ou navegador e a Carteira do Google para verificação on-line

Formatos, credenciais e recursos compatíveis

A Carteira do Google é compatível com documentos de identificação digitais baseados em mdoc ISO pelo OpenID4VP (versão 1.0) no Android 9 (nível 28 da API) e versões mais recentes e em navegadores compatíveis.

Credenciais e atributos aceitos

Consulte os identificadores doctype_value (mDL, passe de identificação, documento de identificação com foto) e os caminhos de declaração de atributos que você pode solicitar à Carteira do Google.

Emissores aceitos e certificados da IACA

Faça o download dos certificados raiz oficiais da IACA para estados dos EUA, emissores internacionais e o emissor Sandbox Utopia para validar issuerAuth.


Etapa A: formatar e assinar a solicitação (lado do servidor)

Para solicitar credenciais de qualquer carteira, você precisa formatar sua solicitação usando o OpenID4VP no seu servidor. É possível solicitar uma credencial específica ou várias em um único objeto dcql_query.

Exemplo de solicitação JSON

Confira um exemplo de solicitação mdoc requestJson para receber credenciais de identidade de qualquer carteira em um dispositivo Android ou na Web.

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

Solicitar criptografia

O client_metadata contém a chave pública de criptografia para cada solicitação. Você precisa armazenar chaves privadas para cada solicitação e usá-las para autenticar e autorizar o token que você recebe do app de carteira.

Metadados integrados do OpenID4VP

Ao formatar sua solicitação de credencial, inclua o campo gw_rp_metadata_bytes no objeto client_metadata (conforme mostrado no exemplo de código de solicitação abaixo). Esse campo contém os metadados da parte confiável codificados em Base64URL exigidos pela Carteira do Google para verificar sua identidade e mostrar sua marca ao usuário.

Payload da solicitação de credencial

O parâmetro credential_request em requestJson contém os campos a seguir.

Credencial específica

{
  "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": {
          // Use org.iso.18013.5.1.mDL for mDL,
          // com.google.wallet.idcard.1 for ID pass, or
          // org.iso.23220.photoid.1 for ID pass (using photo ID document type)
          "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
          }
        ]
      }
    ]
  },
  "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
        ],
        "issuerauth_alg_values": [
          -7
        ]
      }
    },
    "gw_rp_metadata_bytes": "<base64url encoded metadata string>"
  }
}

Qualquer credencial qualificada

Veja o exemplo de solicitação para mDL, passe de identificação e passe de identificação (usando o tipo de documento de identificação com foto). O usuário pode prosseguir com qualquer uma delas.

{
  "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 pass
        "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 type 3: ID pass (using photo ID document type)
        "id": "photo_id-request",
        "format": "mso_mdoc",
        "meta": {
          "doctype_value": "org.iso.23220.photoid.1"
        },
        "claims": [
          {
            "path": [
              "org.iso.23220.1",
              "family_name"
            ],
            "intent_to_retain": false // set this to true if you are saving the value of the field
          },
          {
            "path": [
              "org.iso.23220.1",
              "given_name"
            ],
            "intent_to_retain": false
          },
          {
            "path": [
              "org.iso.23220.1",
              "age_over_18"
            ],
            "intent_to_retain": false
          }
        ]
      }
    ]
    credential_sets : [
      {
        "options": [
          [ "mdl-request" ],
          [ "id_pass-request" ],
          [ "photo_id-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
        ],
        "issuerauth_alg_values": [
          -7
        ]
      }
    },
    "gw_rp_metadata_bytes": "<base64url encoded metadata string>"
  }
}

Você pode solicitar qualquer número de atributos compatíveis de qualquer credencial de identidade armazenada na Carteira do Google.

Solicitações assinadas

As solicitações assinadas (solicitações de autorização protegidas por JWT) encapsulam sua solicitação de apresentação verificável em um JSON Web Token (JWT) assinado criptograficamente usando sua infraestrutura de PKI, garantindo a integridade da solicitação e comprovando sua identidade para a Carteira do Google.

Pré-requisitos

Antes de implementar as mudanças de código para solicitações assinadas, verifique se você tem:

  • Chave privada:você precisa de uma chave privada (por exemplo, curva elíptica ES256) para assinar a solicitação, gerenciada no seu servidor. Para testes de sandbox como parte confiável, use a chave privada de teste de sandbox.
  • Certificado:você precisa de um certificado X.509 padrão derivado do seu par de chaves.
  • Registro:verifique se o certificado público (ou a CA raiz para registradores de verificação) é confiável para a Carteira do Google.

Lógica de construção de solicitações

Ao criar e assinar sua solicitação do OpenID4VP, preste muita atenção ao formato de codificação exato esperado para cada campo. Misturar base64 e base64url ou preenchimento (=) vai causar falha na validação da assinatura ou da origem:

Campo Codificação / formato obrigatório Caracteres e preenchimento
client_id (x509_hash:<hash>) base64url sem preenchimento Usa o alfabeto seguro para URL (-, _); remove o = final
expected_origins (android:apk-key-hash:<hash>) Base64 padrão sem preenchimento Usa o alfabeto padrão (+, /); remove o = final
expected_origins (https://...) URL em minúsculas sem barras no final Exemplo: https://example.com (sem / no final)
Cabeçalho JWS x5c Base64 padrão com preenchimento Usa o alfabeto padrão (+, /); mantém o preenchimento = final

Para criar uma solicitação, use sua chave privada e envolva o payload em um 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()

            # Important: Use URL-safe Base64 (base64url: '-', '_') without padding ('=') for client_id
            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
            # Important: Use standard Base64 (not URL-safe) without padding for android:apk-key-hash:
            # origin = f"android:apk-key-hash:{base64.b64encode(apk_cert_hash).decode('utf-8').rstrip('=')}"
            # Format for web origin (lowercase URL without trailing slash): origin = "https://example.com"
            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.
            # Important: Use standard Base64 ('+', '/') WITH padding ('=') for x5c
            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

Etapa B: acionar a API (lado do cliente)

Toda a solicitação de API precisa ser gerada no lado do servidor. Dependendo da plataforma, transmita o JSON gerado para as APIs da plataforma.

No app (Android)

Para solicitar credenciais de identidade dos seus apps Android, siga estas etapas:

Atualizar dependências

No build.gradle do projeto, atualize as dependências para usar o Gerenciador de credenciais (Beta):

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

Configurar o Gerenciador de credenciais

Para configurar e inicializar um objeto CredentialManager, adicione uma lógica parecida com esta:

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

Atributos de identidade da solicitação

Em vez de especificar parâmetros individuais para solicitações de identidade, o app fornece todos eles juntos como uma string JSON no CredentialOption. O Gerenciador de credenciais transmite essa string JSON para as carteiras digitais disponíveis sem examinar o conteúdo. Cada carteira é responsável por:

  • Analisar a string JSON para entender a solicitação de identidade.
  • Determinar quais das credenciais armazenadas, se houver, atendem à solicitação.

Recomendamos que os parceiros criem as solicitações no servidor, mesmo para integrações de apps Android.

Você vai usar o requestJson de Formatar e assinar a solicitação como o request na chamada de função 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)
    }
}

Processar a resposta da credencial

Depois de receber uma resposta da carteira, verifique se ela foi bem-sucedida e se contém a resposta 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}")
    }
}

A resposta credentialJson contém um identityToken (JWT) criptografado, definido pelo W3C. O app Carteira é responsável por criar essa resposta.

Exemplo:

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

Transmita essa resposta de volta ao servidor para validar a autenticidade. Consulte Descriptografar e validar a resposta.

Web

Para solicitar credenciais de identidade usando a API Digital Credentials no Chrome ou em outros navegadores compatíveis, faça a seguinte solicitação:

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

Envie a resposta dessa API de volta ao servidor para validar a resposta da credencial.


Etapa C: descriptografar e validar a resposta (lado do servidor)

Depois que a carteira retornar o identityToken (JWT) criptografado, faça uma validação rigorosa do lado do servidor antes de confiar nos dados.

Descriptografar a resposta

Use a chave privada correspondente à chave pública enviada no client_metadata da solicitação para descriptografar o JWE. Isso gera um vp_token.

Exemplo em 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 vai resultar em um JSON vp_token com a credencial:

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

Reconstruir o SessionTranscript e validar o DeviceResponse

  1. Crie o SessionTranscript da ISO/IEC 18013-5:2021 com uma estrutura de transferência específica para Android ou Web:
SessionTranscript = [
  null,                // DeviceEngagementBytes not available
  null,                // EReaderKeyBytes not available
  [
    "OpenID4VPDCAPIHandover",
    AndroidHandoverDataBytes   // BrowserHandoverDataBytes for Web
  ]
]

Para transferências do Android e da Web, use o mesmo nonce que você usou para gerar credential_request.

Transferência do 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()

Transferência do navegador

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

Usando o SessionTranscript, a resposta do dispositivo precisa ser validada de acordo com a cláusula 9 da norma ISO/IEC 18013-5:2021.

Essa validação inclui quatro verificações:

  1. Verifique o certificado do emissor:extraia a cadeia de certificados de assinatura do emissor de issuerAuth e valide-a em relação aos certificados raiz confiáveis da IACA. Consulte Emissores e certificados IACA compatíveis (e adicione o certificado do sandbox Utopia ao testar com um ID de teste do sandbox).
  2. Verificar a assinatura do MSO (ISO/IEC 18013-5, seção 9.1.2).
  3. Calcule e verifique ValueDigests para elementos de dados (ISO/IEC 18013-5, seção 9.1.2).
  4. Verificar a assinatura de deviceSignature (ISO/IEC 18013-5, seção 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
}

Etapa D (opcional): confirmação de idade que preserva a privacidade (ZKP)

Para oferecer suporte a provas de conhecimento zero (por exemplo, verificar se um usuário tem mais de 18 anos sem ver a data de nascimento exata), mude o formato da solicitação para mso_mdoc_zk e forneça a configuração zk_system_type necessária.

Para uma visão geral de alto nível do que é o ZKP e os recursos dele, consulte as Perguntas frequentes.

  ...
  "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
            {
              ...

Você vai receber uma prova de conhecimento zero criptografada da carteira. É possível validar essa prova em relação aos certificados IACA do emissor usando a biblioteca longfellow-zk do Google.

O verifier-service contém um servidor baseado em Docker pronto para implantação que permite validar a resposta em relação aos certificados IACA do emissor.

É possível modificar certs.pem para gerenciar os certificados do emissor da IACA em que você quer confiar.


SDKs, implementações de referência e suporte

Use nossas bibliotecas de código aberto, o servidor de referência e a ferramenta de verificação da Web para acelerar sua implementação:

Recurso / Biblioteca O que oferece Link
Implementação de referência de verificadores de identidade Servidor e cliente de amostra que demonstram a geração de solicitações OpenID4VP, a assinatura JWS, a descriptografia JWE e a validação de resposta mdoc. Repositório do GitHub
SDK do Multipaz Biblioteca de código aberto (OpenWallet Foundation), incluindo DeviceResponseParser para decodificação CBOR, reconstrução de SessionTranscript e validação de assinatura ISO/IEC 18013-5/7. openwallet-foundation/multipaz
Biblioteca Longfellow ZKP e serviço de verificação Biblioteca de código aberto e servidor baseado em Docker para verificar declarações de idade e atributos de prova de conhecimento zero (mso_mdoc_zk). google/longfellow-zk
Ferramenta interativa de verificação da Web Verificador da Web hospedado para testar solicitações da API W3C Digital Credentials / OpenID4VP na Carteira do Google. verifier.multipaz.org
Especificação do OpenID4VP 1.0 Especificação oficial do protocolo OpenID for Verifiable Presentations 1.0. Especificação do OpenID4VP
Perguntas frequentes e suporte ao desenvolvedor Respostas para perguntas comuns sobre integração técnica ou envie um e-mail para wallet-identity-rp-support@google.com se precisar de ajuda com a depuração. Perguntas frequentes sobre integração técnica

Próxima etapa