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:
- Conceder permissões delegadas a um aplicativo Web.
- Chamar o Microsoft Graph em um aplicativo Web para um usuário conectado.
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).
No menu Centro de administração do Microsoft Entra, selecione Aplicativos.
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.
Escolha Adicionar uma permissão e selecione APIs da Microsoft e Microsoft Graph.
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.
Importante
Se você não configurar o Serviço de Aplicativo para retornar um token de acesso utilizável, receberá um erro CompactToken parsing failed with error code: 80049217 ao chamar as APIs do Microsoft Graph no código.
Acesse o Azure Resource Explorer e, usando a árvore de recursos, localize seu aplicativo Web. A URL do recurso será semelhante a https://resources.azure.com/subscriptions/subscriptionId/resourceGroups/SecureWebApp/providers/Microsoft.Web/sites/SecureWebApp20200915115914.
O Azure Resource Explorer agora está aberto com seu aplicativo Web selecionado na árvore de recursos.
Na parte superior da página, selecione Leitura/Gravação para permitir a edição dos recursos do Azure.
No navegador esquerdo, faça uma busca detalhada até config>authsettingsV2.
Na exibição authsettingsV2, selecione Editar.
Localize a seção de logon de identityProviders ->azureActiveDirectory e adicione as seguintes configurações de loginParameters:
"loginParameters":[ "response_type=code id_token","scope=openid offline_access profile https://graph.microsoft.com/User.Read" ]."identityProviders": { "azureActiveDirectory": { "enabled": true, "login": { "loginParameters":[ "response_type=code id_token", "scope=openid offline_access profile https://graph.microsoft.com/User.Read" ] } } } },Salve as configurações selecionando PUT. Essa configuração pode levar vários minutos para entrar em vigor. Seu aplicativo Web agora está configurado para acessar o Microsoft Graph com um token de acesso adequado. Se você não fizer isso, o Microsoft Graph retornará um erro informando que o formato do token compacto está incorreto.
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:
Observação
A biblioteca Microsoft.Identity.Web não é necessária no seu aplicativo Web para autenticação/autorização básica nem para autenticar solicitações no Microsoft Graph. Só é possível realizar chamadas a APIs downstream com segurança quando o módulo de autenticação/autorização do Serviço de Aplicativo está habilitado.
No entanto, a autenticação/autorização do Serviço de Aplicativo foi projetada para cenários de autenticação mais básicos. Para cenários mais complexos (lidando com declarações personalizadas, por exemplo), você precisa da biblioteca Microsoft.Identity.Web ou da Biblioteca de Autenticação da Microsoft. Há um pouco mais de trabalho de instalação e configuração no início, mas a biblioteca Microsoft.Identity.Web pode ser executada junto com o módulo de autenticação/autorização do Serviço de Aplicativo. Posteriormente, quando o aplicativo Web precisar lidar com cenários mais complexos, você poderá desabilitar o módulo de autenticação/autorização do Serviço de Aplicativo e o Microsoft.Identity.Web já fará parte do aplicativo.
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://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 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:
- Excluir os recursos do Azure criados durante as etapas do tutorial.
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:
- Conceder permissões delegadas a um aplicativo Web.
- Chamar o Microsoft Graph em um aplicativo Web para um usuário conectado.