Início Rápido: Conectar usuários e chamar o Microsoft Graph em um aplicativo da Plataforma Universal do Windows - Microsoft identity platform

Artigo
06/18/2024

Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como um aplicativo UWP (Plataforma Universal do Windows) pode conectar usuários e obter um token de acesso para chamar a API do Microsoft Graph.

Confira Como o exemplo funciona para ver uma ilustração.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Visual Studio

Observação

As versões 4.61.0 e superiores do MSAL.NET não oferecem suporte à Plataforma Universal do Windows (UWP), Xamarin Android e Xamarin iOS. Recomendamos que você migre seus aplicativos UWP para estruturas modernas, como o WINUI. Leia mais sobre a substituição em Anunciando a substituição futura do MSAL.NET para Xamarin e UWP.

Registrar e baixar o aplicativo de início rápido

Você tem duas opções para iniciar o aplicativo de início rápido:

[Express] Opção 1: Registrar e configurar o aplicativo automaticamente e, em seguida, baixar seu exemplo de código
[Manual] Opção 2: Registrar e configurar manualmente o aplicativo e o exemplo de código

Opção 1: Registrar e configurar o aplicativo automaticamente e, em seguida, baixar seu exemplo de código

Acesse a experiência de início rápido do Centro de administração do Microsoft Entra – Registros de aplicativo.
Insira um nome para seu aplicativo e selecione Registrar.
Siga as instruções para baixar e configurar automaticamente o novo aplicativo.

Opção 2: Registrar e configurar manualmente o aplicativo e o exemplo de código

Etapa 1: Registre seu aplicativo

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à solução, siga estas etapas:

Entre no Centro de administração do Microsoft Entra.
Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.
Navegue até Identidade>Aplicativos>Registros de aplicativo e selecione Novo registro.
Insira um Nome para seu aplicativo, por exemplo, UWP-App-calling-MsGraph. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
Na seção Tipos de conta com suporte, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft (por exemplo, Skype, Xbox, Outlook.com) .
Selecione Registrar para criar o aplicativo e registre a ID do Aplicativo (cliente) para uso em uma etapa posterior.
Em Gerenciar, selecione Autenticação.
Selecione Adicionar uma plataforma>Aplicativos móveis e de área de trabalho.
Em URIs de redirecionamento, selecione https://login.microsoftonline.com/common/oauth2/nativeclient.
Selecione Configurar.

Etapa 2: Baixe o projeto

Baixar o aplicativo de exemplo da UWP

Dica

Para evitar erros causados por limitações de comprimento do caminho no Windows, é recomendável extrair os arquivos em um diretório próximo à raiz da unidade.

Etapa 3: configurar o projeto

Extraia o arquivo .zip para uma pasta local próxima à raiz da unidade. Por exemplo, em C:\Azure-Samples.
Abra o projeto no Visual Studio. Instale a carga de trabalho de desenvolvimento da Plataforma Universal do Windows e componentes de SDK individuais, se solicitado.
Em MainPage.Xaml.cs, altere o valor da variável ClientId para a ID do Aplicativo (Cliente) do aplicativo registrado anteriormente.
```
private const string ClientId = "Enter_the_Application_Id_here";
```
Você pode encontrar a ID do Aplicativo (cliente) no painel Visão geral do aplicativo no Centro de administração do Microsoft Entra (Identidade>Aplicativos>Registros de aplicativo>{Registro do seu aplicativo}).
Crie e selecione um novo certificado de teste autoassinado para o pacote:
1. No Gerenciador de Soluções, clique duas vezes no arquivo Package.appxmanifest.
2. Selecione Empacotamento>Escolher Certificado...>Criar... .
3. Digite uma senha e selecione OK. Um certificado chamado Native_UWP_V2_TemporaryKey.pfx é criado.
4. Selecione OK para fechar a caixa de diálogo Escolher um certificado e verifique se você vê Native_UWP_V2_TemporaryKey.pfx no Gerenciador de Soluções.
5. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto Native_UWP_V2 e selecione Propriedades.
6. Selecione Assinatura e selecione o .pfx criado no menu suspenso Escolha um arquivo de chave de nome forte.

Etapa 4: Executar o aplicativo

Para executar o aplicativo de exemplo no computador local:

Na barra de ferramentas do Visual Studio, escolha a plataforma certa (provavelmente x64 ou x86, não ARM). O dispositivo de destino deve ser alterado de Dispositivo para Computador Local.
Selecione Depurar>Iniciar Sem Depuração.

Se for solicitado que você faça isso, primeiro será necessário habilitar Modo de Desenvolvedor e, em seguida, Iniciar Sem Depurar novamente para iniciar o aplicativo.

Quando a janela do aplicativo for exibida, você poderá selecionar o botão Chamar a API do Microsoft Graph, insira suas credenciais e dê consentimento às permissões solicitadas pelo aplicativo. Se tiver êxito, o aplicativo exibirá algumas informações de token e os dados obtidos da chamada à API do Microsoft Graph.

Como o exemplo funciona

Diagrama mostrando como o aplicativo de exemplo gerado por este início rápido funciona.

MSAL.NET

MSAL (Microsoft.Identity.Client) é a biblioteca usada para conectar usuários e solicitar tokens de segurança. Os tokens de segurança são usados para acessar uma API protegida pela plataforma de identidade da Microsoft. Você pode instalar a MSAL executando o comando abaixo no Console do Gerenciador de Pacotes do Visual Studio:

Install-Package Microsoft.Identity.Client

Inicialização da MSAL

Você pode adicionar a referência da MSAL adicionando o seguinte código:

using Microsoft.Identity.Client;

Em seguida, a MSAL é inicializada usando o seguinte código:

public static IPublicClientApplication PublicClientApp;
PublicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                                                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                                                    .Build();

O valor de ClientId é a ID do aplicativo (cliente) do aplicativo registrado no centro de administração do Microsoft Entra. Você pode encontrar esse valor na página Visão Geral do aplicativo no centro de administração do Microsoft Entra.

Solicitando tokens

A MSAL tem dois métodos para adquirir tokens em um aplicativo UWP: AcquireTokenInteractive e AcquireTokenSilent.

Obter um token de usuário interativamente

Algumas situações exigem forçar os usuários a interagir com a plataforma de identidade da Microsoft por meio de uma janela pop-up para validar as credenciais deles ou para dar consentimento. Alguns exemplos incluem:

A primeira vez que os usuários entram no aplicativo
Quando os usuários precisam reinserir suas credenciais porque a senha expirou
Quando seu aplicativo está solicitando acesso a um recurso com o qual o usuário precisa consentir
Quando a autenticação de dois fatores é necessária

authResult = await PublicClientApp.AcquireTokenInteractive(scopes)
                      .ExecuteAsync();

O parâmetro scopes contém os escopos que estão sendo solicitados, como { "user.read" } para o Microsoft Graph ou { "api://<Application ID>/access_as_user" } para APIs da Web personalizadas.

Obter um token de usuário no modo silencioso

Use o método AcquireTokenSilent para obter tokens para acessar recursos protegidos após o método inicial AcquireTokenInteractive. Não convém exigir que o usuário valide suas credenciais sempre que precisar acessar um recurso. Na maioria das vezes, você quer aquisições e renovação de tokens sem nenhuma interação do usuário

var accounts = await PublicClientApp.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await PublicClientApp.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();

scopes contém os escopos que estão sendo solicitados, por exemplo, { "user.read" } para o Microsoft Graph ou { "api://<Application ID>/access_as_user" } para as APIs Web personalizadas.
firstAccount especifica a primeira conta de usuário no cache (a MSAL é compatível com vários usuários em um único aplicativo).

Ajuda e suporte

Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.

Próximas etapas

Experimente o tutorial de área de trabalho do Windows para ver um guia passo a passo completo sobre a criação de aplicativos e novos recursos, incluindo uma explicação completa deste início rápido.

Tutorial UWP – Chamar a API do Graph

Compartilhar via