Usando a Biblioteca de Carteira do Microsoft Entra com ID Verificada

Artigo
04/02/2024

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

Pré-requisitos

Android Studio instalado no Mac / Windows e um dispositivo de teste Android. Você precisa ativar o modo de desenvolvedor em seu dispositivo de teste Android.
Uma conta de programador Apple, Mac com Xcode e um dispositivo de teste iOS com o modo de programador ativado. A versão iOS precisa ter 16 anos ou mais.
Instale o aplicativo QR Code Reader no seu dispositivo de teste. O aplicativo WalletLibraryDemo não vem com a capacidade de digitalizar códigos QR, então você precisa do aplicativo QR Code Reader para escanear os códigos QR.

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

Nota

Use a Biblioteca de Carteira mais recente disponível para obter suporte para a curva P-256 compatível com NIST usada pela Verified ID desde fevereiro de 2024.

O que é a Microsoft Entra Wallet Library?

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

Quando devo usar a Biblioteca de Carteira Microsoft Entra?

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

Você pode usar o Microsoft Authenticator e um aplicativo móvel usando a Biblioteca da Carteira lado a lado no mesmo dispositivo móvel. O Autenticador, se instalado, será o aplicativo que registrou 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 deep links incorporados em páginas HTML que dependem do protocolo openid:// resultará na inicialização do Microsoft Authenticator.

A Microsoft usa a Biblioteca de Carteira Microsoft Entra?

Sim, a Biblioteca da Carteira é usada pelo Microsoft Authenticator. Algumas funcionalidades podem aparecer primeiro no Autenticador, mas é nossa ambição disponibilizá-las na Biblioteca da Carteira.

Qual é o esforço de adicionar a Microsoft Entra Wallet Library ao meu aplicativo?

Você adiciona a Biblioteca da Carteira ao seu projeto de aplicativo móvel adicionando uma dependência maven para Android e adicionando uma dependência cocoapod para iOS.

iOS
Android

Para iOS, adicione o pod WalletLibrary ao seu 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.1'
}

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

iOS
Android

/// 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.

Obter os URLs de solicitação. A Biblioteca da Carteira não vem com nenhuma funcionalidade para digitalizar um código QR ou similar. A obtenção do URL do pedido através de métodos como a leitura de um código QR deve ser adicionada por si.
Armazenando as credenciais. A Biblioteca da Carteira cria a chave privada e pública usada para assinar respostas e armazena isso no dispositivo, mas não vem com nenhuma funcionalidade para armazenar credenciais. Você precisa gerenciar o armazenamento de credenciais para seu aplicativo móvel.
Interface do usuário. Qualquer representação visual das credenciais armazenadas e da interface do usuário para conduzir o processo de emissão e apresentação deve ser implementada por você.

Aplicação Wallet Library Demo

A Biblioteca da Carteira vem com um aplicativo de demonstração no repositório GitHub que está pronto para uso sem modificações. 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 apresentação no mínimo. Para começar rapidamente, você pode usar o aplicativo QR Code Reader para escanear 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 webapp que emita credenciais e faça solicitações de apresentação de credenciais. O webapp de demonstração pública do Woodgrove é usado para essa finalidade neste tutorial.

Criando o exemplo do Android

Na sua máquina de desenvolvedor com o Android Studio, faça o seguinte:

Baixe ou clone o repositório GitHub da Biblioteca da Carteira Android. Você não precisa da pasta walletlibrary e pode excluí-la se quiser.
Inicie o Android Studio e abra a pasta pai da walletlibrarydemo
Selecione o menu Construir e, em seguida, Criar projeto. Este passo leva algum tempo.
Conecte seu dispositivo de teste Android via cabo USB ao seu laptop
Selecione seu dispositivo de teste no Android Studio e clique no botão Executar (triângulo verde)

Emissão de credenciais usando o exemplo do Android

Inicie o aplicativo WalletLibraryDemo
No seu laptop, inicie o site https://aka.ms/vcdemo de demonstração pública e faça o seguinte
1. Introduza o seu Nome e Apelido e prima Seguinte
2. Selecione Verificar com True Identity
3. Clique em Tirar uma selfie e Carregar documento de identificação emitido pelo governo. A demonstração usa dados simulados e você não precisa fornecer uma selfie real ou um ID.
4. Clique em Avançar e OK
Digitalize o código QR com seu aplicativo QR Code Reader em seu dispositivo de teste e, em seguida, copie o URL completo exibido no aplicativo QR Code Reader. Lembre-se do código PIN.
Volte para o aplicativo WalletLibraryDemo e cole o URL da área de transferência
Pressione o botão CREATE REQUEST
Quando o aplicativo baixa a solicitação, ele mostra uma tela como abaixo. Clique no retângulo branco, que é uma caixa de texto, e insira o código PIN exibido na página do navegador. Em seguida, clique no botão COMPLETAR .
Quando a emissão for concluída, o aplicativo de demonstração exibirá as declarações na credencial

Apresentando 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.

O aplicativo WalletLibraryDemo deve exibir alguns detalhes de credenciais na tela inicial se você tiver emitido uma credencial com êxito.
Na demonstração do Woodgrove no navegador, clique em Retornar ao Woodgrove se ainda não tiver feito isso e continue com a etapa 3 Acesse o portal personalizado.
Digitalize o código QR com a aplicação QR Code Reader no seu dispositivo de teste e, em seguida, copie o URL completo para a área de transferência.
Volte para o aplicativo WalletLibraryDemo e cole no URL e clique no botão CREATE REQUEST
O aplicativo recupera a solicitação de apresentação e exibe as credenciais correspondentes que você tem na memória. Neste caso, você só tem um. Clique nele para que a pequena marca de seleção apareça e, em seguida, clique no botão CONCLUIR para enviar a resposta da apresentação

Criando o exemplo do iOS

Na sua máquina de desenvolvimento Mac com Xcode, faça o seguinte:

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 a WalletLibrary
Definir foco no projeto WalletLibraryDemo
Altere o ID da Equipa para o ID da Equipa de Programadores Apple.
Selecione o menu Produto e, em seguida, Compilar. Este passo leva algum tempo.
Conecte seu dispositivo de teste iOS via cabo USB ao seu laptop
Selecione seu dispositivo de teste no Xcode
Selecione o menu Produto e, em seguida, Executar ou clique no triângulo de execução

Emitindo credenciais usando o exemplo do iOS

Inicie o aplicativo WalletLibraryDemo
No seu laptop, inicie o site https://aka.ms/vcdemo de demonstração pública e faça o seguinte
1. Introduza o seu Nome e Apelido e prima Seguinte
2. Selecione Verificar com True Identity
3. Clique em Tirar uma selfie e Carregar documento de identificação emitido pelo governo. A demonstração usa dados simulados e você não precisa fornecer uma selfie real ou um ID.
4. Clique em Avançar e OK
Digitalize o código QR com seu aplicativo QR Code Reader em seu dispositivo de teste e, em seguida, copie o URL completo exibido no aplicativo QR Code Reader. Lembre-se do código PIN.
Volte para o aplicativo WalletLibraryDemo e cole o URL da área de transferência
Pressione o botão Create Request (Criar solicitação)
Quando o aplicativo baixa a solicitação, ele mostra uma tela como abaixo. Clique no texto Adicionar Pin para ir para uma tela onde você pode inserir o código PIN, em seguida, clique no botão Adicionar para voltar e, finalmente, clique no botão Concluir .
Quando a emissão for concluída, o aplicativo de demonstração exibirá as declarações na credencial.

Apresentando credenciais usando o exemplo do iOS