Guia de início rápido: conectar usuários e chamar o Microsoft Graph em um aplicativo da área de trabalho do Windows

Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como um aplicativo do WPF (Windows Presentation Foundation) pode conectar usuários e obter um token de acesso para chamar a API do Microsoft Graph. O aplicativo da área de trabalho que você cria usa o fluxo de código de autorização emparelhado com o padrão PKCE (Chave de Prova para Troca de Códigos).

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

Pré-requisitos

• Visual Studio com a carga de trabalho de desenvolvimento da Plataforma Universal do Windows instalada

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

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

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

Etapa 1: Registre seu aplicativo

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

1. Entre no Centro de administração do Microsoft Entra.
2. 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.
3. Navegue até Identidade>Aplicativos>Registros de aplicativo e selecione Novo registro.
4. Insira um Nome para seu aplicativo, por exemplo, Win-App-calling-MsGraph. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
5. 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) .
6. Selecione Registrar para criar o aplicativo.
7. Em Gerenciar, selecione Autenticação.
8. Selecione Adicionar uma plataforma>Aplicativos móveis e de área de trabalho.
9. Na seção URI de Redirecionamento, clique em https://login.microsoftonline.com/common/oauth2/nativeclient. Além disso, em URI de redirecionamento personalizado adicione ms-appx-web://microsoft.aad.brokerplugin/{client_id}, desse modo {client_id} será a ID do aplicativo (cliente) do seu aplicativo (o mesmo GUID que será exibido na caixa de seleção msal{client_id}://auth).
10. Selecione Configurar.

Etapa 2: Baixe o projeto

Baixe o aplicativo de exemplo do WPF

Etapa 3: configurar o projeto

1. Extraia o arquivo zip para uma pasta local mais próxima da raiz do disco, por exemplo, C:\Azure-Samples.

2. Abra o projeto no Visual Studio.

3. Edite App.Xaml.cs e substitua os valores dos campos ClientId e Tenant pelo seguinte código:

   private static string ClientId = "Enter_the_Application_Id_here";
   private static string Tenant = "Enter_the_Tenant_Info_Here";
   

Em que:

• Enter_the_Application_Id_here - é a ID do aplicativo (cliente) que você registrou.

  Para encontrar os valores da ID do aplicativo (cliente), acesse a página Visão Geral do Centro de administração do Microsoft Entra.

• Enter_the_Tenant_Info_Here - é definido como uma das seguintes opções:

  • Se seu aplicativo dá suporte a Contas neste diretório organizacional, substitua esse valor pela ID do Locatário ou pelo Nome do locatário (por exemplo, contoso.microsoft.com)

  • Se seu aplicativo dá suporte a Contas em qualquer diretório organizacional, substitua esse valor por organizations

  • Se o seu aplicativo der suporte a Contas em qualquer diretório organizacional e contas pessoais Microsoft, substitua esse valor por common.

    Para encontrar os valores da ID do d1iretório (locatário) e dos Tipos de conta compatíveis, acesse a página Visão geral no Centro de administração do Microsoft Entra.

Etapa 4: Executar o aplicativo

Para criar e executar o aplicativo de exemplo no Visual Studio, selecione o Menu de depuração>Iniciar Depuração ou pressione a tecla F5. O MainWindow do aplicativo é exibido.

Quando a janela principal do aplicativo for exibida, selecione o botão Chamar a API do Microsoft Graph. Você será solicitado a entrar usando sua conta do Microsoft Entra (conta corporativa ou de estudante) ou as credenciais da conta Microsoft (live.com, outlook.com).

Se estiver executando o aplicativo pela primeira vez, você será solicitado a fornecer consentimento para permitir que o aplicativo acesse seu perfil de usuário e entre com você. Depois de consentir com as permissões solicitadas, o aplicativo exibe que você fez logon com êxito. Você deverá ver algumas informações básicas de token e dados de usuário obtidos da chamada para a API do Microsoft Graph.

Mais informações

Como o exemplo funciona

MSAL.NET

MSAL (Microsoft.Identity.Client) é a biblioteca usada para conectar usuários e solicitar tokens 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 -IncludePrerelease

Inicialização da MSAL

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

using Microsoft.Identity.Client;

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

IPublicClientApplication publicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .Build();

Solicitando tokens

A MSAL tem dois métodos para adquirir tokens: 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 suas credenciais 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 app.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();

Obter um token de usuário no modo silencioso

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. Você pode usar o método AcquireTokenSilent para obter tokens para acessar recursos protegidos após o método AcquireTokenInteractive inicial:

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

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.