Учебник. Доступ к Microsoft Graph из защищенного приложения .NET от имени пользователя
Узнайте, как получить доступ к Microsoft Graph из веб-приложения, работающего в Службе приложений Azure.
Предположим, вам нужно обращаться из веб-приложения к Microsoft Graph и выполнять какие-либо действия от имени пользователя, выполнившего вход. В этом разделе описывается, как предоставить делегированные разрешения веб-приложению и получить сведения о профиле пользователя, выполнившего вход, из идентификатора Microsoft Entra.
В этом руководстве описано следующее:
- предоставить веб-приложению делегированные разрешения;
- вызвать Microsoft Graph из веб-приложения для пользователя, выполнившего вход.
Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начинать работу.
Необходимые компоненты
- Веб-приложение, выполняющееся в Службе приложений Azure, с включенным модулем проверки подлинности или авторизации Службы приложений.
Предоставление доступа к интерфейсу для вызова Microsoft Graph
Теперь, когда вы включили проверку подлинности и авторизацию в веб-приложении, веб-приложение регистрируется в платформа удостоверений Майкрософт и поддерживается приложением Microsoft Entra. На этом шаге вы предоставите веб-приложению разрешения для доступа к Microsoft Graph для пользователя. (Технически вы предоставляете приложению Microsoft Entra веб-приложения разрешения на доступ к приложению Microsoft Graph Microsoft Entra для пользователя.)
В Центре администрирования Microsoft Entra выберите "Приложения".
Поочередно выберите Регистрация приложений>Собственные приложения>View all applications in this directory (Просмотреть все приложения в этом каталоге). Щелкните имя веб-приложения и выберите Разрешения API.
Щелкните Добавить разрешения, а затем выберите API-интерфейсы Майкрософт, а также Microsoft Graph.
Щелкните Делегированные разрешения, а затем выберите из списка User.Read. Выберите Добавить разрешения.
Настройка службы приложений для возвращения используемых маркеров доступа
Теперь у веб-приложения есть необходимые разрешения для доступа к Microsoft Graph от имени вошедшего в систему пользователя. На этом шаге настройте проверку подлинности и авторизацию в Службе приложений, чтобы получить пригодный к использованию маркер доступа для обращения к Microsoft Graph. На этом шаге вам понадобится добавить область User.Read для подчиненной службы (Microsoft Graph): https://graph.microsoft.com/User.Read.
Важно!
Если вы не настроите в Службе приложений возврат пригодного к использованию маркера доступа, при вызове API Microsoft Graph из кода возникнет ошибка CompactToken parsing failed with error code: 80049217.
Перейдите к обозревателю ресурсов Azure и с помощью дерева ресурсов найдите нужное веб-приложение. URL-адрес ресурса должен выглядеть приблизительно так: https://resources.azure.com/subscriptions/subscriptionId/resourceGroups/SecureWebApp/providers/Microsoft.Web/sites/SecureWebApp20200915115914.
Теперь откроется обозреватель ресурсов Azure с представлением дерева ресурсов, в котором выделено это веб-приложение.
В верхней части страницы выберите Чтение и запись, чтобы внести изменения в обозревателе ресурсов Azure.
В браузере слева перейдите к разделу config>authsettingsV2.
В представлении authsettingsV2 выберите Изменить.
Найдите раздел login в identityProviders ->azureActiveDirectory и добавьте следующие параметры 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" ] } } } },Сохраните настройки, выбрав PUT. Эти настройки могут вступить в силу через несколько минут. Теперь веб-приложение настроено для доступа к Microsoft Graph с использованием правильного маркера доступа. В противном случае Microsoft Graph вернет ошибку с сообщением о неправильном формате компактного маркера.
Вызов Microsoft Graph с помощью .NET
Теперь веб-приложение имеет требуемые разрешения и правильно включает идентификатор клиента Microsoft Graph в параметры входа.
С помощью библиотеки Microsoft.Identity.Web веб-приложение получает маркер доступа для проверки подлинности в Microsoft Graph. В версии 1.2.0 и более поздних библиотека Microsoft.Identity.Web поддерживает интеграцию и параллельную работу с модулем проверки подлинности и авторизации Службы приложений. Microsoft.Identity.Web определяет, что веб-приложение размещено в службах приложений и получает маркер доступа из модуля проверки подлинности и авторизации служб приложений. Затем этот маркер доступа передается в составе запросов, которые прошли проверку подлинности, в API Microsoft Graph.
Просмотреть этот код как часть примера приложения можно здесь:
Примечание.
Библиотека Microsoft.Identity.Web не требуется в веб-приложении для обычной проверки подлинности и авторизации или для проверки подлинности запросов в Microsoft Graph. Вы можете безопасно вызывать нижестоящие API, если включен только модуль проверки подлинности и авторизации Службы приложений.
Но проверка подлинности и авторизация Службы приложений предназначены только для самых простых сценариев проверки подлинности. Для более сложных сценариев (например, для обработки пользовательских утверждений) нужно использовать библиотеку Microsoft.Identity.Web или библиотеку проверки подлинности Майкрософт. Ее установка и настройка займет немного больше времени, но библиотека Microsoft.Identity.Web может работать параллельно с модулем проверки подлинности и авторизации Службы приложений. Позже, когда веб-приложению потребуется работа с более сложными сценариями, вы сможете отключить модуль проверки подлинности и авторизации Службы приложений, а Microsoft.Identity.Web останется частью приложения.
Установка пакетов клиентских библиотек
Установите в проект пакеты NuGet Microsoft.Identity.Web и Microsoft.Identity.Web.MicrosoftGraph с помощью интерфейса командной строки .NET Core или консоли диспетчера пакетов в Visual Studio.
Командная строка .NET Core
Откройте командную строку и перейдите в каталог с файлом проекта.
Выполните команды установки.
dotnet add package Microsoft.Identity.Web.MicrosoftGraph
dotnet add package Microsoft.Identity.Web
Консоль диспетчера пакетов
Откройте проект или решение в Visual Studio, а затем — консоль, выбрав Средства>Диспетчер пакетов NuGet>Консоль диспетчера пакетов.
Выполните команды установки.
Install-Package Microsoft.Identity.Web.GraphServiceClient
Install-Package Microsoft.Identity.Web
Startup.cs
В файле Startup.cs метод AddMicrosoftIdentityWebApp добавляет Microsoft.Identity.Web в веб-приложение. Метод AddMicrosoftGraph добавляет поддержку Microsoft Graph. Сведения об управлении добавочным согласием и условным доступом см . в этом разделе.
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 задает конфигурацию для библиотеки Microsoft.Identity.Web. В Центре администрирования Microsoft Entra выберите "Приложения" в меню портала и выберите Регистрация приложений. Выберите регистрацию приложения, созданную при включении модуля проверки подлинности и авторизации Службы приложений. (Регистрация приложения должна иметь то же имя, что и ваше веб-приложение.) Идентификатор клиента и идентификатор клиента можно найти на странице обзора регистрации приложения. Доменное имя можно найти на странице обзора Microsoft Entra для вашего клиента.
Graph определяет конечную точку Microsoft Graph и начальные области, которые нужны для приложения.
{
"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": "*"
}
Вызов Microsoft Graph от имени пользователя
В следующем примере показано, как вызвать Microsoft Graph от имени выполнившего вход пользователя и получить сведения об этом пользователе. Объект GraphServiceClient внедряется в контроллер, а проверка подлинности уже автоматически настроена библиотекой 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;
}
}
}
Очистка ресурсов
Если вы выполнили все шаги из этого учебника, состоящего из нескольких частей, то уже создали службу приложений, план размещения службы приложений и учетную запись хранения в группе ресурсов. Вы также создали регистрацию приложения в идентификаторе Microsoft Entra. Если ресурсы и регистрация приложения больше не нужны, удалите их, чтобы за них не взималась плата.
В этом руководстве описано следующее:
- удалять ресурсы Azure, созданные при работе с этим учебником.
Удаление группы ресурсов
В меню портала Azure щелкните Группы ресурсов и выберите группу ресурсов, содержащую службу приложений и план службы приложений.
Щелкните Удалить группу ресурсов. Одновременно с группой ресурсов удаляются все содержащиеся в ней ресурсы.
Выполнение этой команды может занять несколько минут.
Удаление регистрации приложения
В Центре администрирования Microsoft Entra выберите "Приложения> Регистрация приложений". Затем выберите созданное вами приложение.
В разделе общих сведений регистрации приложения выберите Удалить.
Следующие шаги
Из этого руководства вы узнали, как:
- предоставить веб-приложению делегированные разрешения;
- вызвать Microsoft Graph из веб-приложения для пользователя, выполнившего вход.