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

Artigo
06/14/2024

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

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

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Visual Studio

Nota

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

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 AMicrosoft Entra - Experiência de início rápido de registros de aplicativos.
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.

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, 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 UWP-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 Registrar para criar o aplicativo e, em seguida, registre a ID do aplicativo (cliente) para uso em uma etapa posterior.
Em Gerir, selecione Autenticação.
Selecione Adicionar uma plataforma>Aplicações móveis e de ambiente de trabalho.
Em Redirecionar URIs, selecione https://login.microsoftonline.com/common/oauth2/nativeclient.
Selecione Configurar.

Passo 2: Transferir o projeto

Baixe o aplicativo de exemplo UWP

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 arquivo .zip para uma pasta local perto da raiz da sua 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 quaisquer componentes individuais do SDK, se solicitado.
Em MainPage.Xaml.cs, altere o ClientId valor da variável 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 (Identity>Applications>App registrations{Your app registrations>}).
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 Embalagem>Escolher certificado...>Criar....
3. Introduza uma palavra-passe e, em seguida, selecione OK. Um certificado chamado Native_UWP_V2_TemporaryKey.pfx é criado.
4. Selecione OK para descartar 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, em seguida, selecione o .pfx criado na lista suspensa Escolha um arquivo de chave de nome forte.

Etapa 4: Executar o aplicativo

Para executar o aplicativo de exemplo em sua máquina local:

Na barra de ferramentas do Visual Studio, escolha a plataforma certa (provavelmente x64 ou x86, não ARM). O dispositivo de destino deve mudar de dispositivo para máquina local.
Selecione Debug (Depurar) >Start Without Debugging (Iniciar Sem Depuração).

Se você for solicitado a fazer isso, talvez seja necessário primeiro habilitar o Modo de Desenvolvedor e, em seguida , Iniciar Sem Depuração novamente para iniciar o aplicativo.

Quando a janela do aplicativo for exibida, você poderá selecionar o botão Chamar API do Microsoft Graph , inserir suas credenciais e consentir com as permissões solicitadas pelo aplicativo. Se for bem-sucedido, o aplicativo exibirá algumas informações de token e dados obtidos da chamada para a API do Microsoft Graph.

Como funciona a amostra

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

MSAL.NET

MSAL (Microsoft.Identity.Client) é a biblioteca usada para entrar 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. Pode instalar a MSAL ao executar o comando seguinte na Consola do Gestor de Pacotes do Visual Studio:

Install-Package Microsoft.Identity.Client

Inicialização da MSAL

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

using Microsoft.Identity.Client;

Em seguida, o MSAL é inicializado 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 é a ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do ClientId 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 adquirir tokens em um aplicativo UWP: 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:

Os usuários pela primeira vez entram no aplicativo
Quando os utilizadores possam ter de reintroduzir as respetivas credenciais por a palavra-passe ter expirado
Quando seu aplicativo está solicitando acesso a um recurso, que o usuário precisa consentir
Quando é necessária autenticação de dois fatores

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

O scopes parâmetro 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

Use o AcquireTokenSilent método para obter tokens para acessar recursos protegidos após o método inicial AcquireTokenInteractive . Você não deseja exigir que o usuário valide suas credenciais toda vez que precisar acessar um recurso. Na maioria das vezes, você deseja aquisições e renovações de tokens sem qualquer 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, como { "user.read" } para o Microsoft Graph ou { "api://<Application ID>/access_as_user" } para APIs da Web personalizadas.
firstAccount especifica a primeira conta de usuário no cache (o MSAL oferece suporte a vários usuários em um único aplicativo).

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.

UWP - Chamar tutorial da Graph API

Partilhar via