Início Rápido: Adquirir um token e chamar a API do Microsoft Graph de um aplicativo da área de trabalho do WindowsQuickstart: Acquire a token and call Microsoft Graph API from a Windows desktop app

Neste início rápido, você aprenderá a programar um aplicativo WPF (Windows Presentation Foundation) .NET de área de trabalho do Windows que pode conectar contas corporativas, pessoais ou de estudante, obter um token de acesso e chamar a API do Microsoft Graph.In this quickstart, you'll learn how to write a Windows desktop .NET (WPF) application that can sign in personal, work and school accounts, get an access token, and call the Microsoft Graph API.

Mostra como o aplicativo de exemplo gerado por este início rápido funciona

Registrar e baixar o aplicativo de início rápidoRegister and download your quickstart app

Você tem duas opções para iniciar o aplicativo de início rápido:You have two options to start your quickstart application:

Opção 1: Registrar e configurar o aplicativo automaticamente e, em seguida, baixar seu exemplo de códigoOption 1: Register and auto configure your app and then download your code sample

  1. Acesse o novo portal do Azure – Registros de aplicativo.Go to the new Azure portal - App registrations.
  2. Insira um nome para seu aplicativo e selecione Registrar.Enter a name for your application and select Register.
  3. Siga as instruções para baixar e configurar automaticamente o novo aplicativo com apenas um clique.Follow the instructions to download and automatically configure your new application with just one click.

Opção 2: Registrar e configurar manualmente o aplicativo e o exemplo de códigoOption 2: Register and manually configure your application and code sample

Etapa 1: Registre seu aplicativoStep 1: Register your application

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à solução manualmente, siga estas etapas:To register your application and add the app's registration information to your solution manually, follow these steps:

  1. Entre no portal do Azure usando uma conta corporativa ou de estudante ou uma conta pessoal da Microsoft.Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.
  2. Se sua conta fornecer acesso a mais de um locatário, selecione sua conta no canto superior direito e defina sua sessão do portal para o locatário desejado do Azure AD.If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the desired Azure AD tenant.
  3. Navegue até a página Registros de aplicativo da plataforma de identidade da Microsoft para desenvolvedores.Navigate to the Microsoft identity platform for developers App registrations page.
  4. Selecione Novo registro.Select New registration.
    • Na seção Nome, insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo, por exemplo, Win-App-calling-MsGraph.In the Name section, enter a meaningful application name that will be displayed to users of the app, for example Win-App-calling-MsGraph.
    • 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) .In the Supported account types section, select Accounts in any organizational directory and personal Microsoft accounts (for example, Skype, Xbox, Outlook.com).
    • Selecione Registrar para criar o aplicativo.Select Register to create the application.
  5. Na lista de páginas para o aplicativo, selecione Autenticação.In the list of pages for the app, select Authentication.
  6. Expanda a seção Desktop + dispositivos.Expand the Desktop + devices section. (Se Desktop + dispositivos não está visível, primeiro clique na faixa superior para exibir a experiência de Autenticação em versão prévia)(If Desktop + devices is not visible, first click the top banner to view the preview Authentication experience)
  7. Na seção URI de redirecionamento, selecione Adicionar URI.Under the Redirect URI section, select Add URI. Digite urn:ietf:wg:oauth:2.0:oob.Type urn:ietf:wg:oauth:2.0:oob.
  8. Clique em Salvar.Select Save.

Etapa 1: Configurar seu aplicativo no portal do AzureStep 1: Configure your application in Azure portal

Para que o exemplo de código deste início rápido funcione, você precisa adicionar uma URL de resposta como urn: ietf:wg:oauth:2.0:oob.For the code sample for this quickstart to work, you need to add a reply URL as urn:ietf:wg:oauth:2.0:oob.

Já configurado Seu aplicativo já está configurado com esses atributos.Already configured Your application is configured with these attributes.

Etapa 2: Baixar seu projeto do Visual StudioStep 2: Download your Visual Studio project

Baixe o projeto do Visual Studio (Exibir o projeto no GitHub)Download the Visual Studio project (View Project on GitHub)

Etapa 3: Configurar o projeto do Visual StudioStep 3: Configure your Visual Studio project

  1. Extraia o arquivo zip para uma pasta local mais próxima da raiz do disco, por exemplo, C:\Azure-Samples.Extract the zip file to a local folder close to the root of the disk, for example, C:\Azure-Samples.

  2. Abra o projeto no Visual Studio.Open the project in Visual Studio.

  3. Edite App.Xaml.cs e substitua os valores dos campos ClientId e Tenant pelo seguinte código:Edit App.Xaml.cs and replace the values of the fields ClientId and Tenant with the following code:

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

Observação

Este guia de início rápido oferece suporte a Enter_the_Supported_Account_Info_Here.This quickstart supports Enter_the_Supported_Account_Info_Here.

Em que:Where:

  • Enter_the_Application_Id_here - é a ID do aplicativo (cliente) que você registrou.Enter_the_Application_Id_here - is the Application (client) ID for the application you registered.
  • Enter_the_Tenant_Info_Here - é definido como uma das seguintes opções:Enter_the_Tenant_Info_Here - is set to one of the following options:
    • 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)If your application supports Accounts in this organizational directory, replace this value with the Tenant Id or Tenant name (for example, contoso.microsoft.com)
    • Se seu aplicativo dá suporte a Contas em qualquer diretório organizacional, substitua esse valor por organizationsIf your application supports Accounts in any organizational directory, replace this value with organizations
    • Se seu aplicativo dá suporte a Contas em qualquer diretório organizacional e contas pessoais da Microsoft, substitua esse valor por commonIf your application supports Accounts in any organizational directory and personal Microsoft accounts, replace this value with common

Dica

Para encontrar os valores de ID do aplicativo (cliente) , ID de diretório (locatário) e Tipos de conta com suporte, vá para a página Visão Geral do aplicativo no portal do Azure.To find the values of Application (client) ID, Directory (tenant) ID, and Supported account types, go to the app's Overview page in the Azure portal.

Mais informaçõesMore information

MSAL.NETMSAL.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.MSAL (Microsoft.Identity.Client) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. Você pode instalar a MSAL executando o comando abaixo no Console do Gerenciador de Pacotes do Visual Studio:You can install MSAL by running the following command in Visual Studio's Package Manager Console:

Install-Package Microsoft.Identity.Client -IncludePrerelease

Inicialização da MSALMSAL initialization

Você pode adicionar a referência da MSAL adicionando o seguinte código:You can add the reference for MSAL by adding the following code:

using Microsoft.Identity.Client;

Em seguida, inicialize a MSAL usando o seguinte código:Then, initialize MSAL using the following code:

public static IPublicClientApplication PublicClientApp;
PublicClientApplicationBuilder.Create(ClientId)
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .Build();
Em que:Where:
ClientId É a ID do aplicativo (cliente) relativa ao aplicativo registrado no portal do Azure.Is the Application (client) ID for the application registered in the Azure portal. Você pode encontrar esse valor na página Visão Geral do aplicativo no portal do Azure.You can find this value in the app's Overview page in the Azure portal.

Solicitando tokensRequesting tokens

A MSAL tem dois métodos para adquirir tokens: AcquireTokenInteractive e AcquireTokenSilent.MSAL has two methods for acquiring tokens: AcquireTokenInteractive and AcquireTokenSilent.

Obter um token de usuário interativamenteGet a user token interactively

Algumas situações exigem forçar os usuários a interagir com o ponto de extremidade da plataforma de identidade da Microsoft por meio de uma janela pop-up para validar suas credenciais ou para dar consentimento.Some situations require forcing users interact with the Microsoft identity platform endpoint through a popup window to either validate their credentials or to give consent. Alguns exemplos incluem:Some examples include:

  • A primeira vez que os usuários entram no aplicativoThe first time users sign in to the application
  • Quando os usuários precisam reinserir suas credenciais porque a senha expirouWhen users may need to reenter their credentials because the password has expired
  • Quando seu aplicativo está solicitando acesso a um recurso com o qual o usuário precisa consentirWhen your application is requesting access to a resource that the user needs to consent to
  • Quando a autenticação de dois fatores é necessáriaWhen two factor authentication is required
authResult = await App.PublicClientApp.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();
Em que:Where:
_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.Contains the scopes being requested, such as { "user.read" } for Microsoft Graph or { "api://<Application ID>/access_as_user" } for custom Web APIs.

Obter um token de usuário no modo silenciosoGet a user token silently

Não convém exigir que o usuário valide suas credenciais sempre que precisar acessar um recurso.You don't want to require the user to validate their credentials every time they need to access a resource. Na maioria das vezes, você quer aquisições e renovação de tokens sem nenhuma interação do usuário.Most of the time you want token acquisitions and renewal without any user interaction. Você pode usar o método AcquireTokenSilent para obter tokens para acessar recursos protegidos após o método AcquireTokenInteractive inicial:You can use the AcquireTokenSilent method to obtain tokens to access protected resources after the initial AcquireTokenInteractive method:

var accounts = await App.PublicClientApp.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await App.PublicClientApp.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();
Em que:Where:
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.Contains the scopes being requested, such as { "user.read" } for Microsoft Graph or { "api://<Application ID>/access_as_user" } for custom Web APIs.
firstAccount Especifica primeiro usuário no cache (a MSAL dá suporte a vários usuários em um mesmo aplicativo).Specifies the first user in the cache (MSAL support multiple users in a single app).

Ajuda e suporteHelp and support

Se você precisar de Ajuda, quiser relatar um problema ou aprender mais sobre as opções de suporte, consulte o seguinte artigo:If you need help, want to report an issue, or want to learn more about your support options, see the following article:

Próximas etapasNext steps

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.Try out the Windows desktop tutorial for a complete step-by-step guide on building applications and new features, including a full explanation of this quickstart.

Ajude-nos a melhorar a plataforma de identidade da Microsoft.Help us improve the Microsoft identity platform. Deixe sua opinião respondendo a uma breve pesquisa de duas perguntas.Tell us what you think by completing a short two-question survey.