البرنامج التعليمي: الوصول إلى Microsoft Graph من تطبيق NET. آمن مثل التطبيق

تعرف على كيفية الوصول إلى Microsoft Graph من تطبيق ويب يعمل على خدمة تطبيقات Azure.

تريد الاتصال بـ Microsoft Graph لتطبيق الويب. من الطرق الآمنة لمنح تطبيق الويب الخاص بك الوصول إلى البيانات استخدام هوية مُدارة يعينها النظام. تسمح الهوية المدارة من معرف Microsoft Entra ل App Service بالوصول إلى الموارد من خلال التحكم في الوصول استنادا إلى الدور (RBAC)، دون الحاجة إلى بيانات اعتماد التطبيق. بعد تعيين هوية مدارة إلى تطبيق الويب الخاص بكم، تتولى Azure مهمة إنشاء شهادة وتوزيعها. لا داعي للقلق بشأن إدارة الأسرار أو بيانات اعتماد التطبيق.

في هذا البرنامج التعليمي، تتعلم كيفية:

• إنشاء هوية مُدارة من قبل النظام على تطبيق ويب.
• إضافة أذونات Microsoft Graph API إلى هوية مُدارة.
• الاتصال بـ Microsoft Graph من تطبيق ويب باستخدام الهويات المدارة.

إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.

المتطلبات الأساسية

• تطبيق ويب يعمل على Azure App Service وتم فيه تمكين وحدة مصادقة/مصادقة خدمة التطبيق .

تفعيل الهوية المدارة في التطبيق

إذا قمت بإنشاء ونشر تطبيق الويب الخاص بك من خلال Visual Studio، فسيتم تمكين الهوية المدارة في التطبيق الخاص بك.

1. في خدمة التطبيق، حدد Identity في الجزء الأيمن ثم حدد System assigned.

2. تحقق من تعيين Status على On. إذا لم يكن كذلك، فحدد Save ثم حدد Yes لتمكين الهوية المُدارة المعينة من قبل النظام. عندما يتم تمكين الهوية المدارة، يتم تعيين الحالة على On ويكون معرف الكائن متاحاً.

3. لاحظ قيمة Object ID، التي ستحتاجها في الخطوة التالية.

منح حق الوصول إلى Microsoft Graph

عند الوصول إلى Microsoft Graph، تحتاج الهوية المدارة إلى الحصول على أذونات مناسبة للعملية التي تريد تنفيذها. حاليا، لا يوجد خيار لتعيين مثل هذه الأذونات من خلال مركز إدارة Microsoft Entra.

1. لتشغيل البرنامج النصي لإضافة أذونات واجهة برمجة التطبيقات من Microsoft Graph المطلوبة إلى الكائن الرئيسي لخدمة الهوية المُدارة.

   بوويرشيل

   # 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"
   

2. بعد تنفيذ البرنامج النصي، يمكنك التحقق في مركز إدارة Microsoft Entra من تعيين أذونات واجهة برمجة التطبيقات المطلوبة للهوية المدارة.

3. انتقل إلى Applications، ثم حدد Enterprise applications. يعرض هذا الجزء جميع مبادئ الخدمة في المستأجر الخاص بك. أضف عامل تصفية ل "نوع التطبيق==الهويات المدارة" وحدد كيان الخدمة للهوية المدارة.

   إذا كنت تتابع هذا البرنامج التعليمي، فهناك اثنتان من أساسيات الخدمة بنفس اسم العرض (SecureWebApp2020094113531، على سبيل المثال). يمثل مبدأ الخدمة الذي يحتوي على عنوان URL للصفحة الرئيسية تطبيق الويب في المستأجر الخاص بك. يجب ألّا يكون لكيان الخدمة الذي يظهر في الهويات المُدارة عنوان URL للصفحة الرئيسية مُدرج، ويجب أن يتطابق معرّف العنصر مع قيمة معرّف العنصر للهوية المُدارة في الخطوة السابقة.

4. حدد أساس الخدمة للهوية المدارة.

   

5. في Overview، حدد Permissions، وسترى الأذونات المضافة لـ Microsoft Graph.

   

استدعاء Microsoft Graph

تُستخدم فئات ChainedTokenCredential وManagedIdentityCredential وEnvironmentCredential للحصول على بيانات اعتماد رمزية للتعليمة البرمجية لتخويل الطلبات إلى Microsoft Graph. أنشئ مثيلًا لفئة ChainedTokenCredential، والتي تستخدم الهوية المُدارة في بيئة "خدمة التطبيق" أو متغيرات بيئة التطوير لإحضار الرموز المميزة وإرفاقها بعميل الخدمة. يحصل مثال التعليمة البرمجية التالي على بيانات اعتماد الرمز المميز المصادق عليه ويستخدمه لإنشاء كائن عميل خدمة، والذي يحصل على المستخدمين في المجموعة.

لرؤية هذا التعليمة البرمجية كجزء من نموذج تطبيق، راجع:

• نموذج على GitHub.

قم بتثبيت حزمة مكتبة العميل Microsoft.Identity.Web.MicrosoftGraph

قم بتثبيت حزمة Microsoft.Identity.Web.MicrosoftGraph NuGet في مشروعك باستخدام واجهة سطر أوامر .NET Core أو وحدة تحكم مدير الحزم في Visual Studio .

سطر الأوامر .NET Core

افتح سطر أوامر، وقم بالتبديل إلى الدليل الذي يحتوي على ملف المشروع الخاص بك.

قوموا بتشغيل أوامر التثبيت.

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

وحدة تحكم مدير الحزم

افتح المشروع / الحل في Visual Studio، وافتح وحدة التحكم باستخدام الأمر Tools > NuGet Package Manager > Package Manager Console .

قوموا بتشغيل أوامر التثبيت.

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

تنظيف الموارد

إذا انتهيت من هذا البرنامج التعليمي ولم تعد بحاجة إلى تطبيق الويب أو الموارد المرتبطة، فقم بتنظيف الموارد التي قمت بإنشائها.

لا تحذف مجموعة الموارد

في مدخل Microsoft Azure، حدد Resource groups من قائمة المدخل وحدد مجموعة الموارد التي تحتوي على خدمة التطبيق وخطة خدمة التطبيق.

حدد حذف مجموعة الموارد لحذف مجموعة الموارد وجميع الموارد.

قد يستغرق تشغيل هذا الأمر عدة دقائق.

الخطوات التالية

في هذا البرنامج التعليمي، نتعلم طريقة القيام بما يأتي:

• إنشاء هوية مُدارة من قبل النظام على تطبيق ويب.
• إضافة أذونات Microsoft Graph API إلى هوية مُدارة.
• الاتصال بـ Microsoft Graph من تطبيق ويب باستخدام الهويات المدارة.

تعرف على كيفية توصيل تطبيق NET Core. أو تطبيق Python أو تطبيق Java أو تطبيق Node.js بقاعدة بيانات.