Como aceitar documentos de identificação da Carteira do Google

On-line

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, primeiro você precisa se inscrever no programa Beta público usando a conta de teste desejada. Em seguida, forneça os detalhes ao seu contato do Google designado.

  • Link dos Termos de Serviço
  • Logotipo
  • Site
  • ID do pacote da Play Store (para integrações de apps Android)
  • 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 digitais, 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.

Experiência do usuário

Quando um aplicativo solicita atributos de identidade, o seguinte processo ocorre:

  1. Identificação de credenciais:o aplicativo consulta as carteiras disponíveis para identificar as credenciais que podem atender à solicitação. Em seguida, o Android apresenta um seletor da interface do sistema, mostrando as informações a serem compartilhadas. Isso permite que o usuário tome uma decisão informada sobre qual credencial usar.

  2. Seleção do usuário e interação com a carteira:o usuário seleciona uma credencial e o Android invoca o app de carteira correspondente para concluir a transação. O app da carteira pode apresentar a própria tela de consentimento ou exigir uma confirmação biométrica.

Resultado:se o usuário consentir, as credenciais de identidade selecionadas serão compartilhadas com o aplicativo solicitante. Se o usuário recusar, um erro será retornado.

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.

Espera-se que o W3C defina formalmente a estrutura dessa solicitação JSON como parte da especificação da API da Web. No entanto, é importante lembrar que a especificação está em rascunho e sujeita a alterações.

Inicialmente, vamos usar o protocolo de visualização para receber documentos de identificação da Carteira do Google. Isso nos permite iniciar a integração e os testes enquanto a especificação da API Web é finalizada.

Confira um exemplo de um mdoc requestJson para o protocolo de visualização:

{
  identity: {
    providers: [{
      holder: {
        selector: {
          format: ['mdoc'],
          type: 'org.iso.18013.5.1.mDL',
          fields: [
            'org.iso.18013.5.1.family_name',
            'org.iso.18013.5.1.portrait',
          ]
        },
        params: {
          nonce: '1234',
          readerPublicKey: '<public_key>',
          extraParamAsNeededByWallets: true,
        },
      },
    }]
  }
}

// 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)
    }
}

// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
    val credential = result.credential
    when (credential) {
        is DigitalCredential -> {
            val responseJson = credential.credentialJson
            validateResponseOnServer(responseJson)
        }
        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.
        }
        is CreateCredentialUnknownException -> {
            // An unknown, usually unexpected, error has occurred. Check the
            // message error for any additional debugging information.
        }
        is CreateCredentialCustomException -> {
            // You have encountered a custom error thrown by the wallet.
            // If you made the API call with a request object that's a
            // subclass of CreateCustomCredentialRequest using a 3rd-party SDK,
            // then you should check for any custom exception type constants
            // within that SDK to match with e.type. Otherwise, drop or log the
            // exception.
        }
        else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
    }
}

A resposta retorna um identityToken (string JSON), definido pelo W3C. O app Carteira é responsável por criar essa resposta.

Exemplo:

{
    "token": "<base64 encoded response>"
}

Enviar o token e o processo no servidor

Ao receber o identityToken, o app precisa transmiti-lo ao servidor do app para verificação. A etapa inicial envolve decodificar o token do formato base64. A matriz de bytes resultante representa os dados CBOR, que aderem ao CDDL a seguir.

CredentialDocument = {
  "version": tstr,       // Set to "ANDROID-HPKE-v1"
  "pkEm": bstr,          // Public key, in uncompressed form
  "cipherText": bstr     // The encrypted data
}

A próxima etapa é calcular o SessionTranscript da ISO/IEC 18013-5:2021 com uma estrutura de transferência específica do Android:

SessionTranscript = [
  null,                // DeviceEngagementBytes not available
  null,                // EReaderKeyBytes not available
  AndroidHandover      // Defined below
]

AndroidHandover = [
  "AndroidHandoverv1", // Version number
  nonce,               // nonce that comes from request
  appId,               // RP package name
  pkRHash,             // The SHA256 hash of the recipient public key
]

O cipherText é criptografado usando a criptografia HPKE. Para descriptografar, use SessionTranscript como os dados autenticados adicionais, junto com a chave privada EC gerada anteriormente e as seguintes configurações:

  • KEM: DHKEM(P-256, HKDF-SHA256)
  • KDF: HKDF-SHA256
  • AEAD: AES-128-GCM

O texto claro resultante são os bytes CBOR de DeviceResponse, conforme definido na ISO/IEC 18013-5:2021. A DeviceResponse precisa ser validada de acordo com a cláusula 9 da ISO/IEC 18013-5:2021. Isso inclui várias etapas, como verificar se o mdoc tem origem em um emissor confiável e se a resposta é assinada pelo dispositivo pretendido. A classe DeviceResponseParser do projeto de credencial de identidade da OpenWallet Foundation pode ser usada como parte desse processo de validação.

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.

Presencial

Para aceitar documentos da Carteira do Google, siga estas etapas:

  • Desenvolva ou adquira um leitor de documentos conforme definido pela norma ISO 18013-5
  • Carregue certificados IACA no leitor para garantir a autenticidade dos documentos aceitos
  • Testar a solução
  • Registre seu aplicativo na Carteira do Google

Crie ou adquira um leitor de documentos conforme definido pela norma ISO 18013-5

Os documentos na Carteira são implementados de acordo com o padrão ISO 18013-5 das carteiras de habilitação para dispositivos móveis. Eles usam o procedimento de QR code ou baseado em NFC com o BLE como mecanismo de transferência de dados. Assim, qualquer dispositivo que possa implementar esses aspectos do padrão pode atuar como um leitor, até mesmo um aplicativo para dispositivos móveis. Como o padrão é aberto, há várias implementações de terceiros disponíveis no mercado. Além disso, é possível implementar a funcionalidade diretamente, se necessário.

Para orientações sobre como implementar a funcionalidade, consulte nosso app Android leitor de referência de código aberto, que implementa a norma ISO e pode aceitar Carteiras de Habilitação para Dispositivos Móveis (mDLs, na sigla em inglês) da Carteira do Google.

Para começar, crie e execute o app leitor de referência:

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

Carregue certificados IACA no leitor para garantir a autenticidade dos documentos aceitos

Para validar uma credencial real, você precisa ter um documento na carteira de um emissor aceito. Confira abaixo uma lista de emissores aceitos na Carteira do Google e links dos certificados deles usados para verificação.

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.

(Opcional) Registre seu aplicativo na Carteira do Google

Para registrar seu aplicativo na Carteira do Google, preencha este formulário.