Tutorial: Acessar Microsoft Graph de um aplicativo .NET seguro como usuário

Saiba como acessar Microsoft Graph de um aplicativo Web em execução no Azure App Service.

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

Neste tutorial, você aprenderá como:

Se você não tiver uma conta Azure, crie uma conta free antes de começar.

Pré-requisitos

• Um aplicativo Web em execução em Azure App Service que tem o módulo de autenticação/autorização App Service habilitado.

Conceder acesso ao front-end para chamar o Microsoft Graph

Depois de habilitar a autenticação e a autorização em seu aplicativo Web, o aplicativo Web será registrado na plataforma de identidade da Microsoft e será apoiado por um aplicativo do Microsoft Entra. Nesta etapa, você concede permissões ao aplicativo Web para acessar Microsoft Graph para o usuário.

1. No centro de administração do Microsoft Entra, selecione Entra ID.

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

3. Selecione Adicionar uma permissão e, em seguida, selecione APIs da Microsoft e, em seguida, Microsoft Graph.

4. Selecione Permissões delegadas e User.Read na lista. Selecione 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 Microsoft Graph como o usuário conectado. Nesta seção, você configurará a autenticação e a autorização do Serviço de Aplicativo para fornecer um token de acesso utilizável para acessar o Microsoft Graph. Nesta etapa, você precisa adicionar o escopo User.Read para o serviço downstream (Microsoft Graph): https://graph.microsoft.com/User.Read.

Chamar Microsoft Graph com .NET

Seu aplicativo Web agora tem as permissões necessárias e também adiciona a ID do cliente do Microsoft Graph aos parâmetros de logon.

Usando o Microsoft. Identity.Web library, 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 integra-se e pode ser executada junto com o módulo de autenticação/autorização do App Service. Microsoft.Identity.Web detecta que o aplicativo web está hospedado no App Service e recupera automaticamente o token de acesso do cabeçalho de solicitação X-MS-TOKEN-AAD-ACCESS-TOKEN que o App Service injeta (consulte Recuperar tokens no código do aplicativo). Você não precisa acessar manualmente esse cabeçalho em seu código. Em seguida, o token de acesso é transmitido para solicitações autenticadas com a Microsoft Graph API.

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 Package Manager

Abra o projeto/solução no Visual Studio e abra o console usando o comando Tools>NuGet Package Manager>Package Manager Console.

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 Microsoft. Identity.Web para seu aplicativo Web. O método AddMicrosoftGraph adiciona suporte a Microsoft Graph. Para obter informações sobre como gerenciar o consentimento incremental e o acesso condicional, leia este artigo.

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

AzureAd especifica a configuração para a biblioteca Microsoft.Identity.Web. No Microsoft Entra admin center, selecione Entra ID no menu do portal e selecione App registrations. 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 para seu locatário.

Graph especifica o ponto de extremidade 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://learn.microsoft.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 Microsoft Graph em nome do usuário

O exemplo a seguir mostra como chamar Microsoft Graph como o usuário conectado e obter algumas informações do usuário. O objeto GraphServiceClient é 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 os 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 no Microsoft Entra ID. Se você escolheu a configuração externa, talvez tenha criado um novo cliente 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

1. No portal do Azure, no menu do portal do Azure, selecione Grupos de recursos.

2. Selecione o grupo de recursos que contém o Serviço de Aplicativo e o Plano do Serviço de Aplicativo.

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

   

Essa ação pode levar vários minutos.

Excluir o registro do aplicativo

1. No Centro de Administração do Microsoft Entra, selecione Registros de Aplicativos. Em seguida, selecione o aplicativo que você criou.

   

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

1. No Centro de administração do Microsoft Entra, navegue até ID do Entra>Visão Geral>Gerenciar locatários.

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

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

Próximas etapas

Neste tutorial, você aprendeu a: