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

Artigo
10/24/2023

Neste início rápido, você baixa e executa um exemplo de código que demonstra como um aplicativo do Windows Presentation Foundation (WPF) pode entrar em usuários e obter um token de acesso para chamar a API do Microsoft Graph. O aplicativo de área de trabalho que você cria usa o fluxo de código de autorização emparelhado com o padrão PKCE (Proof Key for Code Exchange).

Consulte Como funciona o exemplo para obter uma ilustração.

Pré-requisitos

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

Registar e transferir a aplicação do início rápido

Tem duas opções para iniciar a aplicação de início rápido:

[Express] Opção 1: registar e configurar automaticamente a sua aplicação e, em seguida, transferir o exemplo de código
[Manual] Opção 2: registar e configurar manualmente a aplicação e o exemplo de código

Opção 1: registar e configurar automaticamente a sua aplicação e, em seguida, transferir o exemplo de código

Vá para o Centro de administração do Microsoft Entra - Experiência de início rápido de registros deaplicativos.
Introduza um nome para a sua aplicação e xelecione Registar.
Siga as instruções para transferir e configurar automaticamente a sua nova aplicação com um só clique.

Opção 2: registar e configurar manualmente a aplicação e o exemplo de código

Passo 1: Registar a aplicação

Gorjeta

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

Para registar a sua aplicação e adicionar as informações de registo da aplicação à sua solução manualmente, siga os passos a seguir:

Inicie sessão 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é Registros do aplicativo Aplicativos de identidade>>, selecione Novo registro.
Introduza um Nome para a sua aplicação, por exemplo Win-App-calling-MsGraph. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
Na secção Tipos de conta suportados, selecione Contas em qualquer diretório organizacional e contas Microsoft pessoais (por exemplo, Skype, Xbox, Outlook.com).
Selecione Registar para criar a aplicação.
Em Gerir, selecione Autenticação.
Selecione Adicionar uma plataforma>Aplicações móveis e de ambiente de trabalho.
Na seção URIs de redirecionamento, selecione https://login.microsoftonline.com/common/oauth2/nativeclient e, em URIs de redirecionamento personalizados, adicione ms-appx-web://microsoft.aad.brokerplugin/{client_id} onde {client_id} está a ID do aplicativo (cliente) do seu aplicativo (o mesmo GUID que aparece na msal{client_id}://auth caixa de seleção).
Selecione Configurar.

Passo 2: Transferir o projeto

Baixe o aplicativo de exemplo WPF

Gorjeta

Para evitar erros causados por limitações de comprimento de caminho no Windows, recomendamos extrair o arquivo ou clonar o repositório em um diretório perto da raiz da unidade.

Etapa 3: Configurar o projeto

Extraia o ficheiro zip para uma pasta local 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 com o código seguinte:

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 - é o ID da Aplicação (cliente) que registou.

Para encontrar o valor da ID do aplicativo (cliente), vá para a página Visão geral do aplicativo no centro de administração do Microsoft Entra.
Enter_the_Tenant_Info_Here - está definido para uma das seguintes opções:
- Se a sua aplicação suportar Contas neste diretório organizacional, substitua este valor pelo Id do Inquilino ou pelo Nome do inquilino (por exemplo, contoso.microsoft.com)
- Se a sua aplicação suportar Contas em qualquer diretório organizacional, substitua este valor por organizations
- Se o seu aplicativo oferecer suporte a Contas em qualquer diretório organizacional e contas pessoais da Microsoft, substitua esse valor por common.
  
  Para encontrar os valores de ID de diretório (locatário) e Tipos de conta suportados, vá para a página Visão geral do aplicativo 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 Depurar Iniciar>depuração ou pressione a tecla F5. A MainWindow do seu aplicativo é exibida.

Quando a janela principal do aplicativo for exibida, selecione o botão Chamar API do Microsoft Graph. Ser-lhe-á pedido para iniciar sessão utilizando as credenciais da sua conta Microsoft Entra (conta escolar ou profissional) ou conta Microsoft (live.com, outlook.com).

Se estiver a executar a aplicação pela primeira vez, ser-lhe-á pedido que forneça consentimento para permitir que a aplicação aceda ao seu perfil de utilizador e inicie sessão. Depois de consentir com as permissões solicitadas, o aplicativo exibe que você fez login com êxito. Você deve ver algumas informações básicas de token e dados do usuário obtidos da chamada para a API do Microsoft Graph.

Mais informações

Como funciona a amostra

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

MSAL.NET

MSAL (Microsoft.Identity.Client) é a biblioteca usada para entrar usuários e solicitar tokens usados para acessar uma API protegida pela plataforma de identidade da Microsoft. Pode instalar a MSAL ao executar o comando seguinte na Consola do Gestor de Pacotes do Visual Studio:

Install-Package Microsoft.Identity.Client -IncludePrerelease

Inicialização da MSAL

Pode adicionar a referência para MSAL, adicionando o código seguinte:

using Microsoft.Identity.Client;

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

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

Em que:	Description
`ClientId`	É a ID do aplicativo (cliente) para o 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.

Solicitar tokens

A MSAL tem dois métodos para comprar tokens: AcquireTokenInteractive e AcquireTokenSilent.

Obter um token de utilizador 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 dar consentimento. Alguns exemplos incluem:

A primeira vez que os utilizadores iniciam sessão na aplicação
Quando os utilizadores possam ter de reintroduzir as respetivas credenciais por a palavra-passe ter expirado
Quando a aplicação está a pedir acesso a um recurso para o qual o utilizador tem de dar consentimento
Quando é necessária autenticação de dois fatores

authResult = await app.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();

Em que:	Description
`_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 utilizador automaticamente

Não vai querer exigir que o utilizador valide as suas credenciais sempre que tiver de aceder a um recurso. Na maioria das vezes, vai querer que as aquisições e renovação de tokens sejam feitas sem qualquer interação do utilizador. Pode utilizar o método AcquireTokenSilent para obter tokens para aceder a 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:	Description
`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.
`firstAccount`	Especifica o primeiro utilizador na cache (a MSAL suporta vários utilizadores numa única aplicação).

Ajuda e suporte

Se precisar de ajuda, quiser comunicar um problema ou quiser saber mais sobre as suas opções de suporte, consulte Ajuda e suporte para programadores.

Próximos passos

Experimente o tutorial do ambiente de trabalho do Windows para obter um guia passo a passo completo sobre a criação de aplicações e novas funcionalidades, incluindo uma explicação completa deste início rápido.

Chamar tutorial da Graph API

Partilhar via