Учебник. Доступ к Microsoft Graph из защищенного приложения .NET от имени приложения

Узнайте, как получить доступ к Microsoft Graph из веб-приложения, работающего в Службе приложений Azure.

Diagram that shows accessing Microsoft Graph.

Необходимо вызвать Microsoft Graph для веб-приложения. Чтобы предоставить веб-приложению доступ к данным, можно использовать управляемое удостоверение, назначаемое системой. Управляемое удостоверение из Azure Active Directory позволяет Службе приложений получать доступ к ресурсам через управление доступом на основе ролей (RBAC) без учетных данных приложения. Когда вы назначаете веб-приложению управляемое удостоверение, Azure создает и распространяет сертификат. Вам не придется беспокоиться об управлении секретами или учетными данными приложения.

В этом руководстве вы узнаете, как:

  • создавать для веб-приложения управляемое удостоверение, назначаемое системой;
  • добавлять разрешения API Microsoft Graph в управляемое удостоверение;
  • вызывать Microsoft Graph из веб-приложения с использованием управляемых удостоверений.

Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начинать работу.

Предварительные требования

Включение управляемого удостоверения в приложении

Если вы создавали и публиковали веб-приложение с помощью Visual Studio, управляемое удостоверение уже включено для этого приложения.

  1. В Службе приложений в области слева выберите Удостоверение, а затем — Назначаемое системой.

  2. Убедитесь, что для параметра Состояние задано значение Вкл. В противном случае выберите Сохранить, а затем — Да, чтобы включить управляемое удостоверение, назначаемое системой. Если управляемое удостоверение включено, для состояния устанавливается значение Вкл. и будет доступен идентификатор объекта.

  3. Запишите значение идентификатора объекта, которое потребуется на следующем шаге.

Screenshot that shows the system-assigned identity.

Предоставление доступа к Microsoft Graph

При доступе к Microsoft Graph управляемому удостоверению требуются соответствующие разрешения для выполнения операции. В настоящее время нет возможности назначать такие разрешения с помощью портала Azure.

  1. Выполните указанный ниже сценарий, чтобы добавить запрошенные разрешения API Microsoft Graph в объект субъекта-службы управляемого удостоверения.

    # Install the module. (You need admin on the machine.)
    # Install-Module AzureAD.
    
    # Your tenant ID (in the Azure portal, under Azure Active Directory > Overview).
    $TenantID="<tenant-id>"
    $resourceGroup = "securewebappresourcegroup"
    $webAppName="SecureWebApp-20201102125811"
    
    # Get the ID of the managed identity for the web app.
    $spID = (Get-AzWebApp -ResourceGroupName $resourceGroup -Name $webAppName).identity.principalid
    
    # Check the Microsoft Graph documentation for the permission you need for the operation.
    $PermissionName = "User.Read.All"
    
    Connect-AzureAD -TenantId $TenantID
    
    # Get the service principal for Microsoft Graph.
    # First result should be AppId 00000003-0000-0000-c000-000000000000
    $GraphServicePrincipal = Get-AzureADServicePrincipal -SearchString "Microsoft Graph" | Select-Object -first 1
    
    # Assign permissions to the managed identity service principal.
    $AppRole = $GraphServicePrincipal.AppRoles | `
    Where-Object {$_.Value -eq $PermissionName -and $_.AllowedMemberTypes -contains "Application"}
    
    New-AzureAdServiceAppRoleAssignment -ObjectId $spID -PrincipalId $spID `
    -ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole.Id
    
  2. После выполнения скрипта на портале Azure можно проверить, что запрашиваемые разрешения API назначены управляемому удостоверению.

  3. Перейдите в раздел Azure Active Directory, а затем выберите Корпоративные приложения. В этой области отображаются все субъект-службы клиента. В разделе Управляемые удостоверения выберите субъект-службу для управляемого удостоверения.

    При работе с этим учебником используются два субъекта-службы с одинаковым отображаемым именем (например, SecureWebApp2020094113531). Субъект-служба с URL-адресом домашней страницы представляет собой веб-приложение в клиенте. Субъект-служба, которая отображается в разделе Управляемые удостоверения, не должна содержать URL-адрес домашней страницы, а идентификатор объекта должен совпадать со значением идентификатора объекта управляемого удостоверения в предыдущем шаге.

  4. Выберите субъект-службу для управляемого удостоверения.

    Screenshot that shows the All applications option.

  5. В разделе Обзор выберите Разрешения и вы увидите добавленные разрешения для Microsoft Graph.

    Screenshot that shows the Permissions pane.

Вызов Microsoft Graph

Классы ChainedTokenCredential, ManagedIdentityCredential и EnvironmentCredential используются для получения учетных данных токена для вашего кода для авторизации запросов в Microsoft Graph. Создайте экземпляр класса ChainedTokenCredential, который использует управляемое удостоверение в среде Службы приложений или переменные среды разработки для выборки токенов и их присоединения к клиенту службы. Приведенный ниже пример кода получает учетные данные токена с пройденной проверкой подлинности и использует их для создания объекта клиента службы, который получает список пользователей в группе.

Просмотреть этот код как часть примера приложения можно здесь:

Установка пакета клиентской библиотеки Microsoft.Identity.Web.MicrosoftGraph

Установите в проект пакет NuGet Microsoft.Identity.Web.MicrosoftGraph с помощью интерфейса командной строки .NET Core или консоли диспетчера пакетов в Visual Studio.

Командная строка .NET Core

Откройте командную строку и перейдите в каталог с файлом проекта.

Выполните команды установки.

dotnet add package Microsoft.Identity.Web.MicrosoftGraph

Консоль диспетчера пакетов

Откройте проект или решение в Visual Studio, а затем — консоль, выбрав Средства>Диспетчер пакетов NuGet>Консоль диспетчера пакетов.

Выполните команды установки.

Install-Package Microsoft.Identity.Web.MicrosoftGraph

Пример .NET

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Azure.Identity;​
using Microsoft.Graph.Core;​​
using System.Net.Http.Headers;

...

public IList<MSGraphUser> Users { get; set; }

public async Task OnGetAsync()
{
    // Create the Graph service client with a ChainedTokenCredential which gets an access
    // token using the available Managed Identity or environment variables if running
    // in development.
    var credential = new ChainedTokenCredential(
        new ManagedIdentityCredential(),
        new EnvironmentCredential());
    var token = credential.GetToken(
        new Azure.Core.TokenRequestContext(
            new[] { "https://graph.microsoft.com/.default" }));

    var accessToken = token.Token;
    var graphServiceClient = new GraphServiceClient(
        new DelegateAuthenticationProvider((requestMessage) =>
        {
            requestMessage
            .Headers
            .Authorization = new AuthenticationHeaderValue("bearer", accessToken);

            return Task.CompletedTask;
        }));

    // MSGraphUser is a DTO class being used to hold User information from the graph service client call
    List<MSGraphUser> msGraphUsers = new List<MSGraphUser>();
    try
    {
        var users =await graphServiceClient.Users.Request().GetAsync();
        foreach(var u in users)
        {
            MSGraphUser user = new MSGraphUser();
            user.userPrincipalName = u.UserPrincipalName;
            user.displayName = u.DisplayName;
            user.mail = u.Mail;
            user.jobTitle = u.JobTitle;

            msGraphUsers.Add(user);
        }
    }
    catch(Exception ex)
    {
        string msg = ex.Message;
    }

    Users = msGraphUsers;
}

Очистка ресурсов

Если вы завершили работу с этим учебником и вам больше не требуется веб-приложение или связанные с ним ресурсы, необходимо очистить созданные ресурсы.

удаление группы ресурсов.

В меню портала Azure щелкните Группы ресурсов и выберите группу ресурсов, содержащую службу приложений и план службы приложений.

Щелкните Удалить группу ресурсов. Одновременно с группой ресурсов удаляются все содержащиеся в ней ресурсы.

Screenshot that shows deleting the resource group.

Выполнение этой команды может занять несколько минут.

Удаление регистрации приложения

В меню портала выберите Azure Active Directory>Регистрация приложений. Затем выберите созданное вами приложение. Screenshot that shows selecting app registration.

В разделе общих сведений регистрации приложения выберите Удалить. Screenshot that shows deleting the app registration.

Дальнейшие действия

В этом руководстве вы узнали, как выполнять следующие задачи:

  • создавать для веб-приложения управляемое удостоверение, назначаемое системой;
  • добавлять разрешения API Microsoft Graph в управляемое удостоверение;
  • вызывать Microsoft Graph из веб-приложения с использованием управляемых удостоверений.

Узнайте, как подключить к базе данных приложения .NET Core, Python, Java или Node.js.