Aceitação on-line de credenciais digitais

Os IDs digitais podem ser aceitos em fluxos no app e na Web. Para aceitar credenciais da Carteira do Google, você precisa:

  1. Integre usando o app ou a Web seguindo as instruções fornecidas e
  2. Preencha este formulário para solicitar e concordar com os Termos de Serviço de aceitação de credenciais da Carteira do Google.

Pré-requisitos

Para testar a apresentação de documentos de identificação de forma digital, primeiro você precisa se inscrever no programa Beta público usando a conta de teste pretendida (que precisa ser uma conta do Gmail). Em seguida, forneça os detalhes ao seu contato do Google.

  • Link dos Termos de Serviço
  • Logotipo
  • Site
  • IDs de pacotes de apps (para integrações de apps Android)
    • Como incluir builds de desenvolvimento / depuração
  • Assinatura do app
    • $ $ANDROID_SDK/build-tools/$BUILD_TOOLS_VERSION/apksigner verify --print-certs -v $APK
  • ID do Gmail usado para participar da versão Beta pública

Formatos de credencial aceitos

Existem vários padrões propostos que definem o formato de dados de documentos de identidade digital, e dois deles estão ganhando força no setor:

  1. mdocs: definidos pela ISO.
  2. Credenciais verificáveis do w3c: definidas pelo w3c.

Embora o Gerenciador de credenciais do Android ofereça suporte aos dois formatos, a Carteira do Google só aceita documentos digitais baseados em mdoc no momento.

Credenciais compatíveis

A Carteira do Google oferece suporte a dois tipos de credenciais:

  1. Carteira de Habilitação para Dispositivos Móveis (mDL)
  2. Documento de identificação

É possível solicitar qualquer credencial no fluxo com uma única mudança de parâmetro.

Experiência do usuário

Esta seção fala sobre o fluxo de apresentação on-line recomendado. O fluxo mostra a apresentação da idade para um app de entrega de bebidas alcoólicas, mas a UX é semelhante para a Web e outros tipos de apresentações.

O usuário é solicitado a verificar a idade no app ou site O usuário vê as credenciais qualificadas disponíveis O usuário vê a página de confirmação na Carteira do Google O usuário faz a autenticação para confirmar o compartilhamento Dados enviados para o app ou site
O usuário é solicitado a verificar a idade no app ou site O usuário vê as credenciais qualificadas disponíveis O usuário vê a página de confirmação na Carteira do Google O usuário faz a autenticação para confirmar o compartilhamento Dados enviados para o app ou site

Palestras

  1. O app ou site tem flexibilidade na criação do ponto de entrada para a API. Como mostrado na etapa 1, recomendamos mostrar um botão genérico, como "Verificar com documento de identificação digital", porque, com o tempo, esperamos que opções além da Carteira do Google estejam disponíveis pela API.
  2. A tela do seletor na etapa 2 é renderizada pelo Android. As credenciais qualificadas são determinadas por uma correspondência entre a lógica de registro fornecida por cada carteira e a solicitação enviada pela parte confiável.
  3. A etapa 3 é renderizada pela Carteira do Google. A Carteira do Google vai mostrar o nome, o logotipo e a política de privacidade fornecidos pelo desenvolvedor nesta tela.

Adicionar um fluxo de documento de identificação digital

Caso o usuário não tenha uma credencial, recomendamos fornecer um link ao lado do botão "Verificar com documento de identificação digital", que vai direcionar o usuário para a Carteira do Google para que ele possa adicionar um documento de identificação digital.

O usuário é solicitado a verificar a idade no app ou site O usuário é direcionado à Carteira do Google para receber um documento de identificação digital
O usuário é solicitado a verificar a idade no app ou site O usuário é direcionado à Carteira do Google para receber um documento de identificação digital

Nenhum documento de identificação digital disponível

Se o usuário selecionar a opção "Verificar com ID digital" sem ter um ID digital, essa mensagem de erro vai aparecer.

O usuário é solicitado a verificar a idade no app ou site O usuário recebe um erro se não tiver um documento de identificação digital
O usuário é solicitado a verificar a idade no app ou site O usuário recebe um erro se não tiver um documento de identificação digital

A API não oferece suporte a um recurso para saber silenciosamente se o usuário tem IDs digitais disponíveis para preservar a privacidade dele. Portanto, recomendamos incluir a opção de link de integração, conforme mostrado.

Formato da solicitação de credenciais de identificação da carteira

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

{
      "requests" : [
        {
          "protocol": "openid4vp",
          "data": {<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ê vai precisar armazenar chaves privadas para cada solicitação e usá-las para autenticar e autorizar o token recebido do app de carteira.

O parâmetro credential_request em requestJson consiste nos seguintes campos.

{
  "response_type": "vp_token",
  "response_mode": "dc_api.jwt",
  "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"
            ]
          },
          {
            "path": [
              "org.iso.18013.5.1",
              "given_name"
            ]
          },
          {
            "path": [
              "org.iso.18013.5.1",
              "age_over_18"
            ]
          }
        ]
      }
    ]
  },
  "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",
          "alg" : "ECDH-ES",
        }
      ]
    },
    "authorization_encrypted_response_alg": "ECDH-ES",
    "authorization_encrypted_response_enc": "A128GCM"
  }
}

É possível solicitar qualquer número de atributos compatíveis de qualquer credencial de identidade armazenada na Carteira do Google.

No app

Para solicitar credenciais de identidade nos 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")
    // optional - needed for credentials support from play services, for devices running Android 13 and below.
    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 semelhante a esta:

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

Solicitar atributos de identidade

Em vez de especificar parâmetros individuais para solicitações de identidade, o app os fornece todos juntos como uma string JSON na CredentialOption. O Gerenciador de credenciais transmite essa string JSON para as carteiras digitais disponíveis sem examinar o conteúdo delas. 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 do formato de solicitação, que consiste no 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)
    }
}

Verificar e validar a resposta

Depois de receber uma resposta da carteira, verifique se ela é bem-sucedida e 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:

"response" : {
  <encrpted_response>
}

Você vai transmitir essa resposta de volta ao servidor para validar a autenticidade dela. Confira as etapas para validar a resposta da credencial.

Web

Para solicitar credenciais de identidade usando a API Digital Credentials no Chrome, você precisa se inscrever no teste de origem da API Digital Credentials.

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

Enviar a resposta desta API de volta ao servidor para validar a resposta de credencial

Etapas para validar a resposta de credencial

Ao receber o identityToken criptografado do seu app ou site, é necessário realizar várias validações antes de confiar na resposta.

  1. Descriptografar a resposta usando a chave privada

    A primeira etapa é descriptografar o token usando a chave privada salva e receber uma resposta em JSON.

    Exemplo de Python:

    from jwcrypto import jwe, jwk

# Retrieve the Private Key from Datastore
reader_private_jwk = jwk.JWK.from_json(jwe_private_key_json_str)

# 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 contendo a credencial

    {
  "vp_token":
  {
    "cred1": "<credential_token>"
  }
}

  2. Criar a transcrição da sessão

    A próxima etapa é criar 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 as transferências do Android / Web, você vai precisar usar o mesmo valor de uso único que usou para gerar credential_request.

    Transferência do Android

        AndroidHandoverData = [
      origin,             // "android:apk-key-hash:<base64SHA256_ofAppSigningCert>",
      clientId,           // "android-origin:<app_package_name>",
      nonce,              // nonce that was used to generate credential request
    ]

    AndroidHandoverDataBytes = hashlib.sha256(cbor2.dumps(AndroidHandoverData)).digest()

    Transferência de navegador

        BrowserHandoverData =[
      origin,               // Origin URL
      clientId,             // "web-origin:<origin>"
      nonce,               //  nonce that was used to generate credential request
    ]

    BrowserHandoverDataBytes = hashlib.sha256(cbor2.dumps(BrowserHandoverData)).digest()

    Usando o SessionTranscript, a DeviceResponse precisa ser validada de acordo com a cláusula 9 da ISO/IEC 18013-5:2021. Isso inclui várias etapas, como:

  3. Verificar o certificado do emissor do estado. Confira os certificados IACA do emissor com suporte.

  4. Verificar a assinatura do MSO (18013-5, seção 9.1.2)

  5. Calcular e verificar os resumos de valor para elementos de dados (18013-5, seção 9.1.2)

  6. Verificar a assinatura deviceSignature (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
}

Testar a solução

Para testar sua solução, crie e execute o app Android detentor da referência de código aberto. Confira abaixo as etapas para criar e executar o app detentor de referência:

  • Clone o repositório dos apps de referência.
  • Abra o projeto no Android Studio.
  • Crie e execute o rótulo appholder no dispositivo ou emulador Android.

Verificação baseada em prova de conhecimento zero (ZKP, na sigla em inglês)

A prova de conhecimento zero (ZKP, na sigla em inglês) é um método criptográfico que permite a um indivíduo (o verificador) provar a um verificador que ele tem uma determinada informação de identidade ou atende a um critério específico (por exemplo, tem mais de 18 anos, tem uma credencial válida) sem revelar os dados reais subjacentes. Essencialmente, é uma maneira de confirmar a veracidade de uma declaração sobre a identidade mantendo os detalhes sensíveis em sigilo.

Os sistemas de identidade digital que dependem do compartilhamento direto de dados de identidade geralmente exigem que os usuários compartilhem informações pessoais excessivas, aumentando o risco de violações de dados e roubo de identidade. Os ZKPs oferecem uma mudança de paradigma, permitindo a verificação com a menor divulgação possível.

Conceitos principais de ZKPs na identidade digital:

  • Confirmador: o indivíduo que tenta comprovar um aspecto da própria identidade.
  • Verificador: a entidade que solicita a comprovação de um atributo de identidade.
  • A prova: um protocolo criptográfico que permite ao verificador convencer o verificador da veracidade da declaração sem revelar as informações secretas.

Principais propriedades das provas de conhecimento zero:

  • Completude: se a declaração for verdadeira e tanto o verificador quanto o verificador forem honestos, o verificador vai ser convencido.
  • Solidez: se a declaração for falsa, um verificador desonesto não poderá (com probabilidade muito alta) convencer um verificador honesto de que ela é verdadeira.
  • Zero-Knowledge: o verificador não descobre nada além do fato de que a declaração é verdadeira. Nenhum dado real da identidade do provedor é exposto.

Para receber uma prova de conhecimento zero da Carteira do Google, mude o formato da solicitação para mso_mdoc_zk e adicione zk_system_type à Solicitação.

  ...
  "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": "2b8e0c49b08eb1801b9bd7a82aa9eb3736a7519fc2b409asdhj1237034", // This will differ if you need more than 1 attribute.
           "num_attributes": 1,
           "version": 1
         }
       ],
       "verifier_message": "challenge"
      },
     "claims": [{
         ...