Partilhar via

Guia de início rápido: inicie sessão de utilizadores e aceda ao Microsoft Graph numa aplicação de ambiente de trabalho do Windows

  • Artigo

Neste guia de início rápido, descarregará e executará um exemplo de código que demonstra como uma aplicação Windows Presentation Foundation (WPF) pode autenticar utilizadores 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

Registe-se e descarregue a sua aplicação Quickstart

Você tem duas opções para iniciar seu aplicativo de início rápido:

Opção 1: Registrar e configurar automaticamente seu aplicativo e, em seguida, baixar seu exemplo de código

  1. Vá para o Centro de administração do Microsoft Entra - Registros de aplicativosexperiência de início rápido.
  2. Introduza um nome para a sua candidatura e selecione Registar.
  3. Siga as instruções para baixar e configurar automaticamente seu novo aplicativo com apenas um clique.

Opção 2: Registrar e configurar manualmente seu aplicativo e exemplo de código

Passo 1: Registe a sua candidatura

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à sua solução manualmente, siga estas etapas:

  1. Entre no centro de administração do Microsoft Entra.
  2. Se tiver acesso a inquilinos múltiplos, utilize o ícone de Definições no menu superior para mudar para o inquilino em que pretende registar a aplicação a partir do menu Diretórios + subscrições.
  3. Navegue até Identidade>Aplicações>Registos de aplicações, selecione Novo registo.
  4. 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.
  5. Na seção Tipos de conta suportados , selecione as Contas em qualquer diretório organizacional e contas pessoais da Microsoft (por exemplo, Skype, Xbox, Outlook.com).
  6. Selecione Registrar para criar o aplicativo.
  7. Em Gerir, selecione Autenticação.
  8. Selecione Adicionar uma plataforma>aplicações móveis e de desktop.
  9. 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} é a ID do aplicativo (cliente) do seu aplicativo (o mesmo GUID que aparece na caixa de seleção msal{client_id}://auth).
  10. Selecione: Configurar:.

Passo 2: Faça o download do projeto

Baixe o aplicativo de exemplo WPF

Dica

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

  1. Extraia o arquivo zip para uma pasta local próxima à raiz do disco, por exemplo, C:\Azure-Samples.

  2. Abra o projeto no Visual Studio.

  3. 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";

Onde:

  • Enter_the_Application_Id_here - é o ID da Aplicação (cliente) para a aplicação que você registou.

    Para encontrar o valor de ID do aplicativo (cliente), vá para a página Visão Geral do do aplicativo no centro de administração do Microsoft Entra.

  • Enter_the_Tenant_Info_Here - é definido como uma das seguintes opções:

    • Se a sua aplicação suportar Contas de neste diretório organizacional, substitua este valor pelo ID do Tenant ou pelo Nome do Tenant (por exemplo, contoso.microsoft.com)

    • Se o seu aplicativo oferecer suporte a Contas em qualquer diretório organizacional, substitua esse valor por organizations

    • Se a sua aplicação suportar Contas em qualquer diretório organizacional e contas pessoais da Microsoft, substitua este valor por common.

      Para encontrar os valores de ID do Diretório (locatário) e de Tipos de conta suportados, aceda à página de Visão Geral do aplicativo no centro de administração do Microsoft Entra.

Etapa 4: Executar o aplicativo

Para criar e executar a aplicação de exemplo no Visual Studio, selecione o menu Depurar >Iniciar Depuraçãoou 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

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

MSAL.NET

MSAL (Microsoft.Identity.Client) é a biblioteca utilizada no sentido de autenticar utilizadores e solicitar tokens utilizados para aceder a 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 -IncludePrerelease

Inicialização do MSAL

Você pode adicionar a referência para MSAL adicionando o seguinte código:

using Microsoft.Identity.Client;

Em seguida, inicialize o MSAL usando o seguinte código:

IPublicClientApplication publicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .Build();
Onde: Descrição
ClientId É o ID da Aplicação (cliente) para a aplicação registrada no centro de administração da Microsoft Entra. Você pode encontrar esse valor na página Visão geral do 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 dar consentimento. Eis alguns exemplos:

  • A primeira vez que os usuários entram no aplicativo
  • Quando os usuários podem precisar reinserir suas credenciais porque a senha expirou
  • Quando seu aplicativo está solicitando acesso a um recurso para o qual o usuário precisa consentir
  • Quando a autenticação de dois fatores é necessária
authResult = await app.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();
Onde: Descrição
_scopes Contém os escopos que estão sendo solicitados, como { "user.read" } para Microsoft Graph ou { "api://<Application ID>/access_as_user" } para APIs da Web personalizadas.

Obter um token de usuário silenciosamente

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. 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();
Onde: Descrição
scopes Contém os escopos que estão sendo solicitados, como { "user.read" } para Microsoft Graph ou { "api://<Application ID>/access_as_user" } para APIs da Web personalizadas.
firstAccount Especifica o primeiro 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 da área de trabalho do Windows para obter um guia passo a passo completo sobre como criar aplicativos e novos recursos, incluindo uma explicação completa deste início rápido.

Tutorial da API do Call Graph