Usando a Biblioteca de Carteira do Microsoft Entra com ID Verificada

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 ser pelo menos IOs 16.
• 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.

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, o aplicativo móvel usa a Biblioteca da Carteira para 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, é 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 deep links incorporados em páginas HTML que dependem do protocolo openid:// inicia o 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.

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

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.

/// 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. Se você gostaria de fornecer suporte para quaisquer outras opções não incorporadas no aplicativo, você precisa adicionar esses recursos por conta própria.
• Armazenando as credenciais. A Biblioteca da Carteira cria a chave privada e pública 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 para seu aplicativo móvel.
• Interface do usuário. Você deve implementar qualquer representação visual de credenciais armazenadas e quaisquer elementos da interface do usuário destinados a conduzir o processo de emissão e apresentação.

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, execute as seguintes etapas:

1. Baixe ou clone o repositório GitHub da Biblioteca da Carteira Android. Você não precisa da pasta da biblioteca da carteira e pode excluí-la se quiser.

2. Inicie o Android Studio e abra a pasta pai da walletlibrarydemo

   

3. Selecione o menu Construir e, em seguida, Criar projeto. Este passo leva algum tempo.

4. Conecte seu dispositivo de teste Android via cabo USB ao seu laptop

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

1. Inicie o aplicativo WalletLibraryDemo

   

2. 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. Selecione Tirar selfie e Carregar identificação emitida pelo governo. A demonstração usa dados simulados e você não precisa fornecer uma selfie real ou um ID.
   4. Selecione Próxima e OK

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

4. Volte para o aplicativo WalletLibraryDemo e cole o URL da área de transferência

5. Pressione o botão CREATE REQUEST

6. 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 PIN exibido na página do navegador. Em seguida, selecione o botão COMPLETE .

   

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

1. Se você emitiu uma credencial com êxito, o aplicativo WalletLibraryDemo deve exibir alguns detalhes da credencial na tela inicial.

   

2. Na demonstração do Woodgrove no navegador, selecione Retornar ao Woodgrove se ainda não tiver feito isso e continue com a etapa 3 Acessar portal personalizado.

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

4. Volte para o aplicativo WalletLibraryDemo e cole no URL e selecione o botão CREATE REQUEST

5. 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, selecione o botão CONCLUIR para enviar a resposta da apresentação

   

Criando o exemplo do iOS

Na sua máquina de desenvolvimento Mac com Xcode, siga os seguintes passos:

1. Baixe ou clone o repositório GitHub da Biblioteca da Carteira do iOS.

2. Inicie o Xcode e abra a pasta de nível superior para a WalletLibrary

3. Definir foco no projeto WalletLibraryDemo

   

4. Altere o ID da Equipa para o ID da Equipa de Programadores Apple.

5. Selecione o menu Produto e, em seguida, Compilar. Este passo leva algum tempo.

6. Conecte seu dispositivo de teste iOS via cabo USB ao seu laptop

7. Selecione seu dispositivo de teste no Xcode

8. Selecione o menu Produto e, em seguida, Executar ou selecione no triângulo de execução

Emitindo credenciais usando o exemplo do iOS

1. Inicie o aplicativo WalletLibraryDemo

   

2. 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. Selecione Tirar selfie e Carregar identificação emitida pelo governo. A demonstração usa dados simulados e você não precisa fornecer uma selfie real ou um ID.
   4. Selecione Próxima e OK

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

4. Volte para o aplicativo WalletLibraryDemo e cole o URL da área de transferência

5. Pressione o botão Create Request (Criar solicitação)

6. Quando o aplicativo conclui o download da solicitação, ele mostra uma tela como o nosso exemplo. Selecione no texto Adicionar pino para ir para uma tela onde você pode inserir o código PIN, em seguida, selecione o botão Adicionar para voltar e, finalmente, selecione o botão Concluir .

   

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

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.

1. Se você emitiu uma credencial com êxito, o aplicativo WalletLibraryDemo exibirá o nome do tipo de credencial na tela inicial.

   

2. Na demonstração do Woodgrove no navegador, selecione Retornar ao Woodgrove se ainda não tiver feito isso e continue com a etapa 3 Acessar portal personalizado.

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

4. Volte para o aplicativo WalletLibraryDemo, limpe a solicitação anterior da caixa de texto, cole o URL e selecione o botão Criar solicitação

5. 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 mude de azul para verde e, em seguida, selecione o botão Concluir para enviar a resposta da apresentação

   

Próximos passos

Saiba como configurar seu locatário para a ID Verificada do Microsoft Entra.