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

Artigo
10/25/2023

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

Acesse a experiência de início rápido do Centro de administração do Microsoft Entra – Registros do aplicativo.
Insira um nome para seu aplicativo e selecione Registrar.
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

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 manualmente, 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, Win-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.
Em Gerenciar, selecione Autenticação.
Selecione Adicionar uma plataforma>Aplicativos móveis e de área de trabalho.
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).
Selecione Configurar.

Etapa 2: Baixe o projeto

Baixe o aplicativo de exemplo do WPF

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 mais próxima da raiz do disco, por exemplo, C:\Azure-Samples.
Abra o projeto no Visual Studio.

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

Diagram showing how the sample app generated by this quickstart works.

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();

Em que:	Descrição
`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: 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();

Em que:	Descrição
`_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 APIs Web personalizadas.

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();

Em que:	Descrição
`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 APIs Web personalizadas.
`firstAccount`	Especifica primeiro usuário no cache (a MSAL dá suporte a vários usuários em um mesmo 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 Chamar a API do Graph

Compartilhar via