Usando a Biblioteca da Carteira do Microsoft Entra com a ID Verificada

Neste tutorial, você aprenderá como um aplicativo móvel pode usar a Biblioteca da Carteira do Microsoft Entra com ID Verificada para emitir e apresentar credenciais verificáveis.

Pré-requisitos

Android Studio instalado no Mac/Windows e em um dispositivo de teste Android. Você precisa habilitar o modo de desenvolvedor no seu dispositivo de teste Android.
Uma conta de desenvolvedor da Apple, Mac com Xcode e um dispositivo de teste do iOS com o modo de desenvolvedor habilitado. A versão do iOS precisa ser pelo menos IOs 16.
Instale o aplicativo Leitor de Código QR em seu dispositivo de teste. O aplicativo WalletLibraryDemo não vem com a capacidade de verificar códigos QR, portanto, você precisa do aplicativo QR Code Reader para verificar os códigos QR.

Você não precisa ser um desenvolvedor de aplicativo móvel para seguir este tutorial e colocar o aplicativo de demonstração em funcionamento. As ferramentas e um dispositivo de teste e a coragem de tentar é tudo o que você precisa. Você também não precisa de um locatário da ID verificada do Microsoft Entra integrado, pois pode testar o aplicativo de demonstração com nosso site de demonstração de ponta a ponta público.

Observação

Use a biblioteca de carteiras mais recente disponível para obter suporte para a curva P-256 em conformidade com NIST usada pela ID Verificada desde fevereiro de 2024.

O que é a Biblioteca de Carteira do Microsoft Entra?

A Biblioteca de Carteira do Microsoft Entra para iOS e Android oferece ao seu aplicativo móvel a capacidade de começar a usar a plataforma ID Verificada do Microsoft Entra. Usando a Biblioteca de Carteiras, o aplicativo móvel usa a Biblioteca de Carteiras para emitir e apresentar credenciais verificáveis de acordo com os padrões do setor.

Quando devo usar a Biblioteca da Carteira do Microsoft Entra?

O Microsoft Authenticator tem toda a funcionalidade para atuar como a carteira da ID Verificada do Microsoft Entra. Mas nos casos em que você não pode usar o Microsoft Authenticator, a Biblioteca da Carteira é sua alternativa. Um exemplo pode ser quando você já tem um aplicativo móvel com o qual os usuários estão familiarizados e onde faz mais sentido incluir a tecnologia de credenciais verificáveis neste aplicativo.

Você pode usar o Microsoft Authenticator e um aplicativo móvel usando a Biblioteca de Carteiras lado a lado no mesmo dispositivo móvel. O Authenticator, se instalado, é o aplicativo que registra o manipulador de protocolo para openid://, portanto, seu aplicativo precisa garantir que as solicitações de emissão e apresentação encontrem seu aplicativo. O uso de links profundos inseridos em páginas HTML que dependem do protocolo openid:// inicia o Microsoft Authenticator.

O Microsoft Authenticator usa a Biblioteca da Carteira do Microsoft Entra?

Sim, a Biblioteca da Carteira é usada pelo Microsoft Authenticator. Alguns recursos podem aparecer primeiro no Authenticator, mas é nossa ambição disponibilizá-los na Biblioteca da Carteira.

Como adicionar a Biblioteca da Carteira do Microsoft Entra ao meu aplicativo?

Adicione a Biblioteca da Carteira ao seu projeto de aplicativo móvel pela adição de uma dependência maven para Android e da adição de uma dependência cocoapod para iOS.

Ios
Andróide

Para iOS, adicione o pod WalletLibrary ao Podfile.

target "YourApp" do
  use_frameworks!
  pod "WalletLibrary", "~> 1.0.1"
end

Para Android, adicione ao build.gradle do seu aplicativo para adicionar a Biblioteca da Carteira como uma dependência.

dependencies {
    implementation 'com.microsoft.entra.verifiedid:walletlibrary:1.0.0'
}

Em seguida, você precisa adicionar algum código para processar as solicitações. Para obter detalhes, consulte o código de exemplo WalletLibraryDemo.

Ios
Andróide

/// Create a verifiedIdClient.
let verifiedIdClient = VerifiedIdClientBuilder().build()

/// Create a VerifiedIdRequestInput using a OpenId Request Uri.
let input = VerifiedIdRequestURL(url: URL(string: "openid-vc://...")!)
let result = await verifiedIdClient.createRequest(from: input)

/// Every external method's return value is wrapped in a Result object to ensure proper error handling.
switch (result) {
case .success(let request):
    /// A request created from the method above could be an issuance or a presentation request. 
    /// In this example, it is a presentation request, so we can cast it to a VerifiedIdPresentationRequest.
    let presentationRequest = request as? VerifiedIdPresentationRequest
case .failure(let error):
    /// If an error occurs, its value can be accessed here.
    print(error)
}

// Create a verifiedIdClient
val verifiedIdClient = VerifiedIdClientBuilder(context).build()

// Create a VerifiedIdRequestInput using a OpenId Request Uri.
val verifiedIdRequestUrl = VerifiedIdRequestURL(Uri.parse("openid-vc://..."))
val verifiedIdRequestResult: Result<VerifiedIdRequest<*>> = verifiedIdClient.createRequest(verifiedIdRequestUrl)

// Every external method's return value is wrapped in a Result object to ensure proper error handling.
if (verifiedIdRequestResult.isSuccess) {
    val verifiedIdRequest = verifiedIdRequestResult.getOrNull()
    val presentationRequest = verifiedIdRequest?.let {
        verifiedIdRequest as VerifiedIdPresentationRequest
    }
} else {
    // If an exception occurs, its value can be accessed here.
    val exception = verifiedIdRequestResult.exceptionOrNull()
}

Em seguida, você precisa lidar com as seguintes tarefas principais em seu aplicativo.

Obtenção das URLs de solicitação. A Biblioteca da Carteira não vem com nenhuma funcionalidade para ler um código QR ou semelhante. Se você quiser fornecer suporte para outras opções não incorporadas ao aplicativo, precisará adicionar esses recursos por conta própria.
Armazenamento das credenciais. A Biblioteca de Carteiras cria a chave pública e privada usada para assinar respostas e as armazena no dispositivo, mas não vem com nenhuma funcionalidade para armazenar credenciais. Você precisa gerenciar o armazenamento de credenciais do seu aplicativo móvel.
Interface do Usuário. Você deve implementar qualquer representação visual de credenciais armazenadas e quaisquer elementos de interface do usuário destinados a impulsionar o processo de emissão e apresentação.

Aplicativo de demonstração da Biblioteca da Carteira

A Biblioteca da Carteira vem com um aplicativo de demonstração no repositório do GitHub que está pronto para uso sem nenhuma modificação. Você só precisa compilá-lo e implantá-lo. O aplicativo de demonstração é uma implementação leve e simples que ilustra a emissão e a apresentação ao mínimo. Para começar rapidamente, você pode usar o aplicativo Leitor de Código QR para ler o código QR e, em seguida, copiá-lo e colá-lo no aplicativo de demonstração.

Para testar o aplicativo de demonstração, você precisa de um aplicativo Web que emita credenciais e faça solicitações de apresentação para credenciais. O aplicativo Web de demonstração pública do Woodgrove é usado para essa finalidade neste tutorial.

Compilando o exemplo do Android

Em seu computador desenvolvedor com o Android Studio, execute as seguintes etapas:

Baixe ou clone o repositório GitHub da Biblioteca da Carteira do Android. Você não precisa da pasta da biblioteca da carteira e pode excluí-la se quiser.
Inicie o Android Studio e abra a pasta pai de walletlibrarydemo
Selecione o menu Compilar e, em seguida, Criar Projeto. Essa etapa leva algum tempo.
Conecte seu dispositivo de teste Android por cabo USB ao seu laptop
Selecione seu dispositivo de teste no Android Studio e selecione o botão Executar (triângulo verde)

Emissão de credenciais usando o exemplo do Android

Iniciar o aplicativo WalletLibraryDemo
Em seu laptop, inicie o site de demonstração pública https://aka.ms/vcdemo e faça o seguinte
1. Insira seu Nome e Sobrenome e pressione Avançar
2. Selecione Verificar com Identidade Verdadeira
3. Selecione Tirar uma selfie e carregar a ID emitida pelo governo. A demonstração usa dados simulados e você não precisa fornecer uma selfie ou uma ID real.
4. Selecione Avançar e OK
Leia o código QR com seu aplicativo leitor de código QR em seu dispositivo de teste e copie a URL completa exibida no aplicativo Leitor de Código QR. Memorize o código pin.
Volte para o aplicativo WalletLibraryDemo e cole a URL da área de transferência
Pressione o botão CRIAR SOLICITAÇÃO
Quando o aplicativo baixa a solicitação, ele mostra uma tela como o exemplo fornecido. Selecione no retângulo branco, que é uma caixa de texto, e insira o código de pino exibido na página do navegador. Em seguida, selecione o botão CONCLUIR .
Depois que a emissão for concluída, o aplicativo de demonstração exibirá as informações na credencial

Apresentação de credenciais usando o exemplo do Android

O aplicativo de exemplo contém a credencial emitida na memória, portanto, após a emissão você pode usá-la para apresentação.

Se você emitiu uma credencial com êxito, o aplicativo WalletLibraryDemo deverá exibir alguns detalhes de credencial na tela inicial.
Na demonstração do Woodgrove no navegador, selecione Retornar ao Woodgrove se você ainda não fez isso e continue com o portal personalizado do Access da etapa 3.
Digitalize o código QR com o aplicativo Leitor de Código QR no seu dispositivo de teste e copie a URL completa para a área de transferência.
Volte para o aplicativo WalletLibraryDemo e cole na URL e selecione o botão CREATE REQUEST
O aplicativo recupera a solicitação de apresentação e exibe as credenciais correspondentes que você tem na memória. Nesse caso, você só tem um. Clique nele para que a marca de seleção seja exibida e, em seguida, selecione o botão COMPLETE para enviar a resposta da apresentação

Compilação do exemplo do iOS

Em seu computador desenvolvedor mac com Xcode, execute as seguintes etapas:

Baixe ou clone o repositório GitHub da Biblioteca da Carteira do iOS.
Inicie o Xcode e abra a pasta de nível superior para o WalletLibrary
Defina o foco no projeto WalletLibraryDemo
Altere a ID da Equipe para sua ID da Equipe de Desenvolvedores da Apple.
Selecione o menu Produto e, em seguida, Compilar. Essa etapa leva algum tempo.
Conectar seu dispositivo de teste iOS por meio de cabo USB ao seu laptop
Selecione seu dispositivo de teste no Xcode
Selecione o menu Produto e, em seguida, Execute ou selecione no triângulo de execução

Emissão de credenciais usando o exemplo do iOS

Iniciar o aplicativo WalletLibraryDemo
Em seu laptop, inicie o site de demonstração pública https://aka.ms/vcdemo e faça o seguinte
1. Insira seu Nome e Sobrenome e pressione Avançar
2. Selecione Verificar com Identidade Verdadeira
3. Selecione Tirar uma selfie e carregar a ID emitida pelo governo. A demonstração usa dados simulados e você não precisa fornecer uma selfie ou uma ID real.
4. Selecione Avançar e OK
Leia o código QR com seu aplicativo leitor de código QR em seu dispositivo de teste e copie a URL completa exibida no aplicativo Leitor de Código QR. Memorize o código pin.
Volte para o aplicativo WalletLibraryDemo e cole a URL da área de transferência
Pressione o botão Criar Solicitação
Quando o aplicativo conclui o download da solicitação, ele mostra uma tela como nosso exemplo. Selecione o texto Adicionar Pin para acessar uma tela na qual você pode inserir o código de fixação e selecione Botão Adicionar para voltar e, por fim, selecione o botão Concluir.
Depois que a emissão for concluída, o aplicativo de demonstração exibirá as informações na credencial.

Apresentação de credenciais usando o exemplo do iOS