Tutorial: Acessar o Microsoft Graph de um aplicativo .NET seguro como o usuário
Saiba como aceder ao Microsoft Graph a partir de uma aplicação Web em execução no Serviço de Aplicações do Azure.
Você deseja adicionar acesso ao Microsoft Graph a partir 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, irá aprender a:
- Conceda permissões delegadas a um aplicativo Web.
- Chame o Microsoft Graph de um aplicativo Web para um usuário conectado.
Se não tiver uma subscrição 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.
Conceder acesso front-end para chamar o Microsoft Graph
Agora que você habilitou a autenticação e a autorização em seu aplicativo Web, o aplicativo Web está registrado na plataforma de identidade da Microsoft e é apoiado por um aplicativo Microsoft Entra. Nesta etapa, você concede ao aplicativo Web permissões para acessar o Microsoft Graph para o usuário. (Tecnicamente, você dá ao aplicativo Microsoft Entra do aplicativo Web as permissões para acessar o aplicativo Microsoft Graph Microsoft Entra para o usuário.)
No centro de administração do Microsoft Entra, selecione Aplicativos.
Selecione Registros de>aplicativos Aplicativos>de propriedade Exibir todos os aplicativos neste diretório. Selecione o nome do aplicativo Web e, em seguida, selecione Permissões de API.
Selecione Adicionar uma permissão e, em seguida, selecione APIs da Microsoft e Microsoft Graph.
Selecione Permissões delegadas e, em seguida, selecione User.Read na lista. Selecione Adicionar permissões.
Configurar o Serviço de Aplicações para devolver 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, você configura 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. 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 CompactToken parsing failed with error code: 80049217 erro ao chamar as APIs do Microsoft Graph em seu código.
Vá para o Gerenciador de Recursos do Azure e, usando a árvore de recursos, localize seu aplicativo Web. A URL do recurso deve ser semelhante a https://resources.azure.com/subscriptions/subscriptionId/resourceGroups/SecureWebApp/providers/Microsoft.Web/sites/SecureWebApp20200915115914.
O Azure Resource Explorer agora é aberto com seu aplicativo Web selecionado na árvore de recursos.
Na parte superior da página, selecione Leitura/Gravação para habilitar a edição de seus recursos do Azure.
No navegador à esquerda, faça drill down para config>authsettingsV2.
Na visualização authsettingsV2, selecione Editar.
Encontre a seção de login de identityProviders ->azureActiveDirectory e adicione as seguintes configurações 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 suas 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 dizendo que o formato do token compacto está incorreto.
Ligue para o 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 login.
Usando a biblioteca Microsoft.Identity.Web, o aplicativo Web obtém um token de acesso para autenticação com o Microsoft Graph. Na versão 1.2.0 e posterior, a biblioteca Microsoft.Identity.Web integra-se e pode ser executada juntamente com o módulo de autenticação/autorização do Serviço de Aplicativo. Microsoft.Identity.Web deteta 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, consulte:
Nota
A biblioteca Microsoft.Identity.Web não é necessária em seu aplicativo Web para autenticação/autorização básica ou para autenticar solicitações com o Microsoft Graph. É possível chamar APIs downstream com segurança apenas com o módulo de autenticação/autorização do Serviço de Aplicativo 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 (manipulação de 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. Mais tarde, quando seu 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 Microsoft.Identity.Web já fará parte do seu aplicativo.
Instalar pacotes de biblioteca cliente
Instale os pacotes NuGet Microsoft.Identity.Web e Microsoft.Identity.Web.MicrosoftGraph em seu projeto usando a interface de linha de comando .NET Core ou o Console do Gerenciador de Pacotes no Visual Studio.
Linha de comando .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
Consola do Gestor de Pacotes
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 AddMicrosoftIdentityWebApp método adiciona Microsoft.Identity.Web ao seu aplicativo Web. O AddMicrosoftGraph método 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
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, selecione Registros de aplicativos. Selecione o registro do aplicativo criado quando você ativou o módulo de autenticação/autorização do Serviço de Aplicativo. (O registro do aplicativo deve ter o mesmo nome do seu aplicativo Web.) Você pode encontrar o ID do locatário e o 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.
O Graph especifica o ponto de extremidade do 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": "*"
}
Ligue para 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 GraphServiceClient objeto é 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;
}
}
}
Clean up resources (Limpar recursos)
Se você concluiu todas as etapas neste tutorial com várias partes, 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 locatário externo. Quando não for mais necessário, exclua esses recursos e o registro do aplicativo para não continuar acumulando cobranças.
Neste tutorial, irá aprender a:
- Exclua os recursos do Azure criados ao seguir o tutorial.
Eliminar 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 seu plano do Serviço de Aplicativo e do Serviço de Aplicativo.
Selecione Excluir grupo de recursos para excluir o grupo de recursos e todos os recursos.
Esse comando pode levar vários minutos para ser executado.
Excluir o registro do aplicativo
No centro de administração do Microsoft Entra, selecione Registros>de aplicativos de aplicativos. Em seguida, selecione o aplicativo que você criou.
Na visão geral de registro do aplicativo, selecione Excluir.
Excluir 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é Visão geral>da identidade>Gerenciar locatários.
Selecione o inquilino que pretende eliminar e, em seguida, selecione Eliminar.
Talvez seja necessário concluir as ações necessárias antes de excluir o locatário. Por exemplo, talvez seja necessário excluir todos os fluxos de usuários e registros de aplicativos no locatário.
Se você estiver pronto para excluir o locatário, selecione Excluir.
Próximos passos
Neste tutorial, ficou a saber como:
- Conceda permissões delegadas a um aplicativo Web.
- Chame o Microsoft Graph de um aplicativo Web para um usuário conectado.