Tutorial: acessar o Microsoft Graph de um aplicativo ;NET protegido como o usuário

Saiba como acessar o Microsoft Graph de um aplicativo Web em execução no Serviço de Aplicativo do Azure.

Você deseja adicionar acesso a Microsoft Graph do seu aplicativo Web e executar alguma ação como o usuário conectado. Esta seção descreve como conceder permissões delegadas ao aplicativo Web e obter as informações de perfil do usuário conectado da ID do Microsoft Entra.

Neste tutorial, você aprenderá a:

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

• Um aplicativo Web em execução no Serviço de Aplicativo do Azure que tem o módulo de autenticação/autorização do Serviço de Aplicativo habilitado.

Permitir acesso de front-end para chamada ao Microsoft Graph

Agora que você habilitou a autenticação e a autorização no aplicativo Web, ele será registrado na plataforma de identidade da Microsoft e terá o suporte de um aplicativo do Microsoft Entra. Nesta etapa, você fornecerá as permissões ao aplicativo Web para acessar o Microsoft Graph para o usuário. (Tecnicamente, você concede ao aplicativo do Microsoft Entra do aplicativo Web as permissões para acessar o aplicativo do Microsoft Entra do Microsoft Graph para o usuário).

1. No menu Centro de administração do Microsoft Entra, selecione Aplicativos.

2. Selecione Registros de aplicativo>Aplicativos próprios>Exibir todos os aplicativos neste diretório. Selecione o nome do aplicativo Web e Permissões de API.

3. Escolha Adicionar uma permissão e selecione APIs da Microsoft e Microsoft Graph.

4. Selecione Permissões delegadas e User.Read na lista. Escolha Adicionar permissões.

Configurar o Serviço de Aplicativo para retornar um token de acesso utilizável

O aplicativo Web agora tem as permissões necessárias para acessar o Microsoft Graph como o usuário conectado. Nesta etapa, configure o recurso de autenticação e autorização do Serviço de Aplicativo para fornecer um token de acesso usado para acessar o Microsoft Graph. Para esta etapa, você precisa adicionar o escopo User.Read para o serviço downstream (Microsoft Graph): https://graph.microsoft.com/User.Read.

Chamar o Microsoft Graph com o .NET

Seu aplicativo Web agora tem a permissão necessária e também adiciona a ID do cliente do Microsoft Graph aos parâmetros de logon.

Usando a biblioteca Microsoft.Identity.Web, o aplicativo Web Obtém um token de acesso para autenticação com Microsoft Graph. Na versão 1.2.0 e posteriores, a biblioteca Microsoft.Identity.Web é integrada com o módulo de autenticação/autorização do Serviço de Aplicativo e pode ser executada junto com ele. A biblioteca Microsoft.Identity.Web detecta que o aplicativo Web está hospedado no Serviço de Aplicativo e obtém o token de acesso do módulo de autenticação/autorização do Serviço de Aplicativo. O token de acesso é então passado para solicitações autenticadas com a API do Microsoft Graph.

Para ver esse código como parte de um aplicativo de exemplo, confira:

• Exemplo no GitHub.

Instalar os pacotes da biblioteca de clientes

Instale os pacotes NuGet Microsoft.Identity.Web e Microsoft.Identity.Web.MicrosoftGraph em seu projeto usando a interface de linha de comando do .NET Core ou o Console do Gerenciador de Pacotes no Visual Studio.

Linha de comando do .NET Core

Abra uma linha de comando e alterne para o diretório que contém o arquivo de projeto.

Execute os comandos de instalação.

dotnet add package Microsoft.Identity.Web.MicrosoftGraph

dotnet add package Microsoft.Identity.Web

Console do Gerenciador de Pacotes

Abra o projeto/a solução no Visual Studio e abra o console do usando o comando Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes.

Execute os comandos de instalação.

Install-Package Microsoft.Identity.Web.GraphServiceClient

Install-Package Microsoft.Identity.Web

Startup.cs

No arquivo Startup.cs, o método AddMicrosoftIdentityWebApp adiciona o Microsoft.Identity.Web ao seu aplicativo Web. O método AddMicrosoftGraph adiciona suporte ao Microsoft Graph. Para obter informações sobre como gerenciar o consentimento incremental e o acesso condicional, leia isto.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Identity.Web;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;

// Some code omitted for brevity.
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
      services.AddOptions();
      string[] initialScopes = Configuration.GetValue<string>("DownstreamApi:Scopes")?.Split(' ');

      services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
              .AddMicrosoftIdentityWebApp(Configuration.GetSection("AzureAd"))
              .EnableTokenAcquisitionToCallDownstreamApi(initialScopes)
                      .AddMicrosoftGraph(Configuration.GetSection("DownstreamApi"))
                      .AddInMemoryTokenCaches(); 

      services.AddAuthorization(options =>
      {
          // By default, all incoming requests will be authorized according to the default policy
          options.FallbackPolicy = options.DefaultPolicy;
      });
      services.AddRazorPages()
          .AddMvcOptions(options => {})                
          .AddMicrosoftIdentityUI();

      services.AddControllersWithViews()
              .AddMicrosoftIdentityUI();
    }
}

appsettings.json

O AzureAd especifica a configuração para a biblioteca Microsoft.Identity.Web. No Centro de Administração do Microsoft Entra, selecione Aplicativos no menu do portal e, em seguida, Registros de aplicativos. Selecione o registro de aplicativo criado quando você habilitou o módulo autenticação/autorização do Serviço de Aplicativo. (O registro de aplicativo deve ter o mesmo nome do aplicativo Web.) Você pode encontrar a ID do locatário e a ID do cliente na página de visão geral do registro do aplicativo. O nome de domínio pode ser encontrado na página de visão geral do Microsoft Entra do seu locatário.

O Graph especifica o ponto de extremidade o Microsoft Graph e os escopos iniciais necessários para o aplicativo.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "[Enter the domain of your tenant, e.g. contoso.onmicrosoft.com]",
    "TenantId": "[Enter 'common', or 'organizations' or the Tenant Id (Obtained from the Microsoft Entra admin center. Select 'Endpoints' from the 'App registrations' blade and use the GUID in any of the URLs), e.g. da41245a5-11b3-996c-00a8-4d99re19f292]",
    "ClientId": "[Enter the Client Id (Application ID obtained from the Microsoft Entra admin center), e.g. ba74781c2-53c2-442a-97c2-3d60re42f403]",
    "ClientSecret": "[Copy the client secret added to the app from the Microsoft Entra admin center]",
    "ClientCertificates": [
    ],
    // the following is required to handle Continuous Access Evaluation challenges
    "ClientCapabilities": [ "cp1" ],
    "CallbackPath": "/signin-oidc"
  },
  "DownstreamApis": {
    "MicrosoftGraph": {
      // Specify BaseUrl if you want to use Microsoft graph in a national cloud.
      // See https://video2.skills-academy.com/graph/deployments#microsoft-graph-and-graph-explorer-service-root-endpoints
      // "BaseUrl": "https://graph.microsoft.com/v1.0",

      // Set RequestAppToken this to "true" if you want to request an application token (to call graph on 
      // behalf of the application). The scopes will then automatically
      // be ['https://graph.microsoft.com/.default'].
      // "RequestAppToken": false

      // Set Scopes to request (unless you request an app token).
      "Scopes": [ "User.Read" ]

      // See https://aka.ms/ms-id-web/downstreamApiOptions for all the properties you can set.
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Chamar o Microsoft Graph em nome do usuário

O exemplo a seguir mostra como chamar o Microsoft Graph como o usuário conectado e obter algumas informações do usuário. O objeto GraphServiceClient foi injetado no controlador, e a autenticação foi configurada para você pela biblioteca Microsoft.Identity.Web.

// Index.cshtml.cs
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Graph;
using System.IO;
using Microsoft.Identity.Web;
using Microsoft.Extensions.Logging;

// Some code omitted for brevity.

[AuthorizeForScopes(Scopes = new[] { "User.Read" })]
public class IndexModel : PageModel
{
    private readonly ILogger<IndexModel> _logger;
    private readonly GraphServiceClient _graphServiceClient;

    public IndexModel(ILogger<IndexModel> logger, GraphServiceClient graphServiceClient)
    {
        _logger = logger;
        _graphServiceClient = graphServiceClient;
    }

    public async Task OnGetAsync()
    {
        try
        {
            var user = await _graphServiceClient.Me.GetAsync();
            ViewData["Me"] = user;
            ViewData["name"] = user.DisplayName;

            using (var photoStream = await _graphServiceClient.Me.Photo.Content.GetAsync())
            {
                byte[] photoByte = ((MemoryStream)photoStream).ToArray();
                ViewData["photo"] = Convert.ToBase64String(photoByte);
            }
        }
        catch (Exception ex)
        {
            ViewData["photo"] = null;
        }
    }
}

Limpar recursos

Se você concluiu todas as etapas neste tutorial de várias partes, você criou um Serviço de Aplicativo, um plano de hospedagem do Serviço de Aplicativo e uma conta de armazenamento em um grupo de recursos. Você também criou um registro de aplicativo na ID do Microsoft Entra. Se você escolheu a configuração externa, talvez você tenha criado um novo locatário externo. Quando não for mais necessário, exclua esses recursos e o registro de aplicativo para que você não continue a acumular encargos.

Neste tutorial, você aprenderá como:

Exclua o grupo de recursos

No portal do Azure, selecione Grupos de recursos no menu do portal e selecione o grupo de recursos que contém o Serviço de Aplicativo e o Plano do Serviço de Aplicativo.

Selecione Excluir grupo de recursos para excluir o grupo de recursos e todos os recursos que ele contém.

Esse comando pode levar vários minutos para ser executado.

Excluir o registro do aplicativo

No centro de administração do Microsoft Entra, selecione Aplicativos>Registros de aplicativo. Em seguida, selecione o aplicativo que você criou.

Na visão geral do registro de aplicativo, selecione Excluir.

Exclua o locatário externo

Se você criou um novo locatário externo, poderá excluí-lo. No centro de administração do Microsoft Entra, navegue até Identidade>Visão geral>Gerenciar locatários.

Selecione o locatário que você deseja excluir e, em seguida, selecione Excluir.

Talvez seja necessário concluir as ações necessárias antes da exclusão do locatário. Por exemplo, talvez seja necessário excluir todos os fluxos de usuário e registros de aplicativo no locatário.

Se estiver pronto para excluir o locatário, selecione Excluir.

Próximas etapas

Neste tutorial, você aprendeu a: