從安全的應用程式以應用程式身分存取 Microsoft Graph

了解如何從在 Azure App Service 上執行的 Web 應用程式存取 Microsoft Graph。

您想要呼叫 Web 應用程式的 Microsoft Graph。 讓 Web 應用程式存取資料的安全方式，是使用系統指派的受控識別。 來自 Microsoft Entra ID 的受控識別可讓 App Service 透過角色型存取控制 (RBAC) 存取資源，而不需要應用程式認證。 將受控識別指派給您的 Web 應用程式後，Azure 會負責建立和散發憑證。 您不需要擔心管理祕密或應用程式認證。

在本教學課程中，您會了解如何：

• 在 Web 應用程式上建立系統指派的受控識別。
• 將 Microsoft Graph API 權限新增至受控識別。
• 使用受控識別從 Web 應用程式呼叫 Microsoft Graph。

如果您沒有 Azure 訂閱，請在開始之前，先建立 Azure 免費帳戶。

必要條件

• 在 Azure App Service 上執行且已啟用 App Service 驗證/授權模組的 Web 應用程式。

啟用應用程式上的受控識別

如果您透過 Visual Studio 建立並發佈 Web 應用程式，則系統會為您的應用程式啟用受控識別。 在應用程式服務中，選取左側窗格中的 [身分識別]，然後選取 [系統指派]。 確定狀態設為開啟。 若未設定為開啟，請依序選取 [儲存] 和 [是] 以啟用系統指派的受控識別。 啟用受控識別時，狀態會設定為「開啟」，且物件識別碼可供使用。

請記下 [物件識別碼] 值，您會在下一個步驟用到。

授與 Microsoft Graph 連線

存取 Microsoft Graph 時，受控識別必須具有要執行之作業的適當權限。 目前沒有任何選項可透過 Microsoft Entra 系統管理中心指派這類權限。 下列指令碼會將要求的 Microsoft Graph API 權限新增至受控識別服務主體物件。

PowerShell

# 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

Azure CLI

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 權限是否已指派給受控識別。

前往 [應用程式]，然後選取 [企業應用程式]。 此窗格會顯示您租用戶中的所有服務主體。 為「應用程式類型 == 受控識別」新增篩選條件，並選取受控識別的服務主體。

如果您遵循本教學課程，則會有兩個具有相同顯示名稱 (例如 SecureWebApp2020094113531) 的服務主體。 具有「首頁 URL」的服務主體代表您租用戶中的 Web 應用程式。 出現在 [受控識別] 中的服務主體不應具有列出的 [首頁 URL]，而且 [物件識別碼] 應該符合上一個步驟中受控識別的物件識別碼值。

在選取受控識別的服務主體。

在 [概觀] 中選取 [權限]，您便會看到 Microsoft Graph 的新增權限。

呼叫 Microsoft Graph

C#

ChainedTokenCredentialManagedIdentityCredential 和 EnvironmentCredential 類別用來取得您程式碼的權杖認證，以授權 Microsoft Graph 的要求。 建立 ChainedTokenCredential 類別的執行個體，此類別會使用 App Service 環境中的受控識別，或開發環境變數來擷取權杖，並將其附加至服務用戶端。 下列程式碼範例會取得已驗證的權杖認證，並用來建立服務用戶端物件，以取得群組中的使用者。

若要在範例應用程式中查看此程式碼，請參閱 GitHub 上的範例。

安裝 Microsoft.Identity.Web.GraphServiceClient 用戶端程式庫套件

使用 .NET 命令列介面 (CLI) 或 Visual Studio 中的套件管理員主控台，在您的專案中安裝 Microsoft.Graph 和 Microsoft.Identity.Web.GraphServiceClient NuGet 套件。

.NET CLI

開啟命令列，並切換至包含專案檔的目錄。

執行安裝命令。

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

套件管理員主控台

在 Visual Studio 中開啟專案/方案，然後使用工具>NuGet 套件管理員>套件管理員主控台命令開啟主控台。

執行安裝命令。

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

範例

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;
}

Node.js

來自 @azure/identity 套件的 DefaultAzureCredential 類別是用來取得程式碼的權杖認證，以授權 Azure 儲存體的要求。 建立 DefaultAzureCredential 類別的執行個體，此執行個體會使用受控識別擷取權杖，並將其附加至服務用戶端。 下列程式碼範例會取得已驗證的權杖認證，並用來建立服務用戶端物件，以取得群組中的使用者。

範例

const graphHelper = require('../utils/graphHelper');
const { DefaultAzureCredential } = require("@azure/identity");

exports.getUsersPage = async(req, res, next) => {

    const defaultAzureCredential = new DefaultAzureCredential();
    
    try {
        const tokenResponse = await defaultAzureCredential.getToken("https://graph.microsoft.com/.default");

        const graphClient = graphHelper.getAuthenticatedClient(tokenResponse.token);

        const users = await graphClient
            .api('/users')
            .get();

        res.render('users', { user: req.session.user, users: users });   
    } catch (error) {
        next(error);
    }
}

若要查詢 Microsoft Graph，此範例會使用 Microsoft Graph JavaScript SDK。

getAuthenticatedClient = (accessToken) => {
    // Initialize Graph client
    const client = graph.Client.init({
        // Use the provided access token to authenticate requests
        authProvider: (done) => {
            done(null, accessToken);
        }
    });

    return client;
}

清除資源

如果您已完成本教學課程，且不再需要 Web 應用程式或相關聯的資源，請清除您建立的資源。

下一步

清理資源