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 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 iOS com o modo de desenvolvedor habilitado. A versão do iOS precisa ser a 16 ou superior.
• Instale o aplicativo Leitor de Código QR em seu dispositivo de teste. O aplicativo WalletLibraryDemo não vem com a capacidade de ler códigos QR, portanto, você precisa do aplicativo Leitor de Código QR para ler 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 de ID Verificada do Microsoft Entra integrado, pois você pode testar o aplicativo de demonstração no nosso site de demonstração público de ponta a ponta.

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 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 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 da Carteira lado a lado no mesmo dispositivo móvel. O Authenticator, 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 localizem seu aplicativo. O uso de links profundos inseridos em páginas HTML que dependem do protocolo openid:// resultará na inicialização do 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?

Você adiciona a Biblioteca da Carteira ao seu projeto de aplicativo móvel por meio da adição de uma dependência maven para Android e da adição de 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.1'
}

Em seguida, você precisa adicionar algum código para processar as solicitações. Para obter detalhes, use o código de exemplo do 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.

• 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. A obtenção da URL de solicitação por meio de métodos como a leitura de um código QR deve ser adicionada por você.
• Armazenamento das credenciais. A Biblioteca da Carteira cria a chave pública e privada 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 do 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ê.

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

No computador do desenvolvedor com o Android Studio, faça o seguinte:

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

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

   

3. Selecione o menu Compilar e, em seguida, Criar Projeto. Essa etapa leva algum tempo.

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

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

1. Iniciar o aplicativo WalletLibraryDemo

   

2. 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. Clique em Tirar uma selfie e Carregar ID emitida pelo governo. A demonstração usa dados simulados e você não precisa fornecer uma selfie ou uma ID real.
   4. Clique em Avançar e OK

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

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

5. Pressione o botão CRIAR SOLICITAÇÃO

6. Quando o aplicativo baixa a solicitação, ele mostra uma tela como mostrado 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 CONCLUIR .

   

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

1. O aplicativo WalletLibraryDemo deverá exibir alguns detalhes de credenciais na tela inicial se você tiver emitido uma credencial com êxito.

   

2. Na demonstração do Woodgrove no navegador, clique em Retornar ao Woodgrove se você ainda não fez isso e continue com a etapa 3 Acessar portal personalizado.

3. Leia o código QR com o aplicativo Leitor de Código QR em seu dispositivo de teste e copie a URL completa para a área de transferência.

4. Volte para o aplicativo WalletLibraryDemo e cole na URL e clique no 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. Nesse caso, você só tem uma. Clique nela para que a pequena marca de marcar seja exibida e clique no botão CONCLUIR para enviar a resposta da apresentação

   

Compilação do exemplo do iOS

No computador desenvolvedor do Mac com Xcode, faça o seguinte:

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 o WalletLibrary

3. Defina o foco no projeto WalletLibraryDemo

   

4. Altere a ID da Equipe para sua ID da Equipe de Desenvolvedores da Apple.

5. Selecione o menu Produto e, em seguida, Compilar. Essa etapa leva algum tempo.

6. Conectar seu dispositivo de teste iOS por meio de cabo USB ao seu laptop

7. Selecione seu dispositivo de teste no Xcode

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

Emissão de credenciais usando o exemplo do iOS

1. Iniciar o aplicativo WalletLibraryDemo

   

2. 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. Clique em Tirar uma selfie e Carregar ID emitida pelo governo. A demonstração usa dados simulados e você não precisa fornecer uma selfie ou uma ID real.
   4. Clique em Avançar e OK

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

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

5. Pressione o botão Criar Solicitação

6. Quando o aplicativo baixa a solicitação, ele mostra uma tela como mostrado abaixo. Clique no texto Adicionar Pin para ir para uma tela na qual você pode inserir o código pin e, em seguida, clique no botão Adicionar para voltar e, por fim, clique no botão Concluir .

   

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

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. O aplicativo WalletLibraryDemo deverá exibir o nome do tipo de credencial na tela inicial se você tiver emitido uma credencial com êxito.

   

2. Na demonstração do Woodgrove no navegador, clique em Retornar ao Woodgrove se você ainda não fez isso e continue com a etapa 3 Acessar portal personalizado.

3. Leia o código QR com o aplicativo Leitor de Código QR em seu dispositivo de teste e copie a URL completa para a área de transferência.

4. Volte para o aplicativo WalletLibraryDemo, desmarque a solicitação anterior da caixa de texto, cole na URL e clique no 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. Nesse caso, você só tem uma. Clique nela para que o pequeno traço de marcar mude de azul para verde clique no botão CONCLUIR para enviar a resposta da apresentação

   

Próximas etapas

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