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

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

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

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

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

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

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

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

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

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

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

2. تحقق من تعيين Status على On.

   إذا لم يكن كذلك، قم بضبطه على التشغيل، ثم اختر حفظ، ثم اختر نعم لتفعيل الهوية المدارة المعينة من النظام. عندما يتم تمكين الهوية المدارة، يتم تعيين الحالة على On ويكون معرف الكائن متاحاً.

3. لاحظ قيمة معرف الكائن ، والتي تحتاجها في القسم التالي.

   

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

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

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

   بوويرشيل

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

2. بعد تشغيل السكريبت، تحقق في مركز إدارة Microsoft Entra من أن صلاحيات API المطلوبة مخصصة للهوية المدارة.

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

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

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

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

   

6. في النظرة العامة، اختر الأجنحة. ترى الأذونات المضافة ل Microsoft Graph.

   

اتصل ب Microsoft Graph

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

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

• عينة على GitHub.

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

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

خط الأوامر الأساسي .NET

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

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

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

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

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

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

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

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

   

3. أدخل اسم مجموعة الموارد للتأكيد.

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

المحتوى ذو الصلة

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

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

تعلم كيفية ربط تطبيق .NET Core أو Node.js app بقاعدة بيانات.