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 fazer o seguinte:

1. Faça a integração 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 seguintes ao contato designado do Google.

• 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 credenciais compatíveis

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: definido 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 com base em mdoc no momento.

Experiência do usuário

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

1. Descoberta de credenciais: o aplicativo consulta as carteiras disponíveis para identificar 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:com o consentimento do usuário, as credenciais de identidade selecionadas são compartilhadas com o aplicativo solicitante. Se o usuário recusar, um erro será retornado.

No aplicativo

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

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 = IdentityCredentialManager.Companion.getClient(context)

Atributos de identidade da solicitação

// Retrieves the user's digital identites from wallet apps for your app.
val getIdentityCredentialOption = GetDigitalCredentialOption(
    requestJson = requestJson, // this is what partners needs to set, example JSON specified below
)
val result = credentialManager.getCredential(request = GetCredentialRequest(credentialOptions, ...)

O autor da chamada do app fornece todos os parâmetros IdentityRequest como uma string JSON. Aqui, ele é representado como o parâmetro requestMatcher da CredentialOption. O Gerenciador de credenciais não se preocupa com o conteúdo desse JSON. Essa solicitação JSON será transmitida diretamente às carteiras, que são responsáveis por analisá-la e decidir quais credenciais podem atender à solicitação. A implementação completa pode ser encontrada no app de exemplo.

Prevemos que o W3C vai definir essa solicitação JSON como um componente da API da Web. Essa padronização vai permitir que os navegadores transmitam diretamente a solicitação para o Android.

Para fornecer uma amostra da aparência dessa solicitação, veja um exemplo de solicitação mdoc:

{
  "selector": {
    "format": [
      "mdoc"
    ],
    "doctype": "org.iso.18013.5.1.mDL",
    "fields": [
      {
        "namespace": "org.iso.18013.5.1",
        "name": "family_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "given_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "age_over_21",
        "intentToRetain": false
      }
    ]
  },
  "nonce": "3cydsUF9xNFyBDAAWOct09hEeSqrFX2WB2r0G6f8Ol0=",
  "readerPublicKey": "BApmGdElal2-1dtafsdHVRa1EpAWZfhlQj_iof2I8L3V8_dCK1gVR0_12E4ZSQ2LcqXRd4zxVeKEqU1wUSgGWUU="
}

A resposta retorna um token de identidade (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 a decodificação do token do formato base64. A matriz de bytes resultante representa os dados CBOR, que seguem a 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 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

Desenvolva 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 o padrão ISO e pode aceitar mDLs 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 destino 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 para verificação.

• Arizona
• Califórnia
• Colorado
• Geórgia
• Maryland

Testar a solução

Para testar sua solução, crie e execute o app Android detentor da referência de código aberto. Confira 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.