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

Мақала
04/05/2023

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

Diagram that shows accessing Microsoft Graph.

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

В этом руководстве описано следующее:

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

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

Необходимые компоненты

Веб-приложение, выполняющееся в Службе приложений Azure, с включенным модулем проверки подлинности или авторизации Службы приложений.

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

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

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

Screenshot that shows the system-assigned identity.

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

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

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

PowerShell
Azure CLI

# Install the module.
# Install-Module Microsoft.Graph -Scope CurrentUser

# The tenant ID
$TenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee"

# The name of your web app, which has a managed identity.
$webAppName = "SecureWebApp-20201106120003" 
$resourceGroupName = "SecureWebApp-20201106120003ResourceGroup"

# The name of the app role that the managed identity should be assigned to.
$appRoleName = "User.Read.All"

# Get the web app's managed identity's object ID.
Connect-AzAccount -Tenant $TenantId
$managedIdentityObjectId = (Get-AzWebApp -ResourceGroupName $resourceGroupName -Name $webAppName).identity.principalid

Connect-MgGraph -TenantId $TenantId -Scopes 'Application.Read.All','AppRoleAssignment.ReadWrite.All'

# Get Microsoft Graph app's service principal and app role.
$serverApplicationName = "Microsoft Graph"
$serverServicePrincipal = (Get-MgServicePrincipal -Filter "DisplayName eq '$serverApplicationName'")
$serverServicePrincipalObjectId = $serverServicePrincipal.Id

$appRoleId = ($serverServicePrincipal.AppRoles | Where-Object {$_.Value -eq $appRoleName }).Id

# Assign the managed identity access to the app role.
New-MgServicePrincipalAppRoleAssignment `
    -ServicePrincipalId $managedIdentityObjectId `
    -PrincipalId $managedIdentityObjectId `
    -ResourceId $serverServicePrincipalObjectId `
    -AppRoleId $appRoleId

az login

webAppName="SecureWebApp-20201106120003"

spId=$(az resource list -n $webAppName --query [*].identity.principalId --out tsv)

graphResourceId=$(az ad sp list --display-name "Microsoft Graph" --query [0].id --out tsv)

appRoleId=$(az ad sp list --display-name "Microsoft Graph" --query "[0].appRoles[?value=='User.Read.All' && contains(allowedMemberTypes, 'Application')].id" --output tsv)

uri=https://graph.microsoft.com/v1.0/servicePrincipals/$spId/appRoleAssignments

body="{'principalId':'$spId','resourceId':'$graphResourceId','appRoleId':'$appRoleId'}"

az rest --method post --uri $uri --body $body --headers "Content-Type=application/json"

После выполнения скрипта можно проверить в Центре администрирования Microsoft Entra, что запрошенные разрешения API назначены управляемому удостоверению.
Перейдите к приложениям и выберите корпоративные приложения. В этой области отображаются все субъект-службы клиента. Добавьте фильтр для "Application type==Managed identityes" и выберите субъект-службу для управляемого удостоверения.

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

Вызов Microsoft Graph

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

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

Пример на GitHub.

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

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

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

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

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

dotnet add package Microsoft.Identity.Web.MicrosoftGraph
dotnet add package Microsoft.Graph

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

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

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

Install-Package Microsoft.Identity.Web.MicrosoftGraph
Install-Package Microsoft.Graph

Пример .NET

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Logging;
using Microsoft.Graph;
using Azure.Identity;

...

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());

    string[] scopes = new[] { "https://graph.microsoft.com/.default" };

    var graphServiceClient = new GraphServiceClient(
        credential, scopes);

    List<MSGraphUser> msGraphUsers = new List<MSGraphUser>();
    try
    {
        //var users = await graphServiceClient.Users.Request().GetAsync();
        var users = await graphServiceClient.Users.GetAsync();
        foreach (var u in users.Value)
        {
            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.

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

Следующие шаги

Из этого руководства вы узнали, как:

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

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

Бөлісу құралы: