Início rápido: iniciar sessão de utilizadores e utilizar o Microsoft Graph numa aplicação da Plataforma Universal do Windows

Neste início rápido, descarrega e executa um exemplo de código que demonstra como uma aplicação da Plataforma Universal do Windows (UWP) pode autenticar utilizadores e obter um token de acesso para invocar 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.
• Estúdio Visual

Registe-se e descarregue a aplicação de início rápido

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

• [Expresso] Opção 1: Registrar e configurar automaticamente seu aplicativo e, em seguida, baixar seu exemplo de código
• [Manual] Opção 2: Registrar e configurar manualmente seu aplicativo e exemplo de código

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

1. Vá para o Centro de administração AMicrosoft Entra - Registo de Aplicações: Experiência de iniciação rápida.
2. Introduza um nome para a sua candidatura e selecione Registar.
3. 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

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

1. Entre no centro de administração do Microsoft Entra.
2. Se tiver acesso a vários inquilinos, utilize o ícone Definições no menu superior para mudar para o inquilino no qual pretende registar a aplicação a partir do menu Diretórios + subscrições.
3. Navegue atéRegistros do >, selecione Novo registro.
4. 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.
5. Na seção Tipos de conta suportados , 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 e, em seguida, registre a ID do aplicativo (cliente) para uso em uma etapa posterior.
7. Em Gerir, selecione Autenticação.
8. Selecione Adicionar uma plataforma>Aplicações móveis e de ambiente de trabalho.
9. Em Redirecionar URIs, selecione https://login.microsoftonline.com/common/oauth2/nativeclient.
10. Selecione Configurar.

Passo 2: Transferir o projeto

Baixe o aplicativo de exemplo UWP

Etapa 3: Configurar o projeto

1. Extraia o arquivo .zip para uma pasta local perto da raiz da sua unidade. Por exemplo, em C:\Azure-Samples.

2. 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.

3. 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 (Registros> do aplicativo ID do Entra>{Seu registro do aplicativo}).

4. 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:

1. 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.

2. Selecione Depurar>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

MSAL.NET

MSAL (Microsoft.Identity.Client) é a biblioteca usada para fazer login de 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. Você pode instalar o MSAL executando o seguinte comando no Console do Gerenciador 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 ClientId do aplicativo (cliente) do aplicativo que você registrou 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 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 a sua aplicação está a solicitar acesso a um recurso, ao qual o utilizador precisa de 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 silenciosamente

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.