البرنامج التعليمي: قم بالوصول إلى Microsoft Graph من تطبيق NET. آمن بصفة المستخدم
تعرف على كيفية الوصول إلى Microsoft Graph من تطبيق ويب يعمل على خدمة تطبيقات Azure.
تريد إضافة الوصول إلى Microsoft Graph من تطبيق الويب الخاص بك وتنفيذ بعض الإجراءات كمستخدم تسجيل الدخول. يصف هذا القسم كيفية منح الأذونات المفوضة لتطبيق الويب والحصول على معلومات ملف تعريف المستخدم الذي سجل الدخول من معرف Microsoft Entra.
في هذا البرنامج التعليمي، تتعلم كيفية:
- منح أذونات مفوضة إلى تطبيق ويب.
- اتصل بـ Microsoft Graph من تطبيق ويب لمستخدم سجل الدخول.
إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.
المتطلبات الأساسية
- تطبيق ويب يعمل على Azure App Service وتم فيه تمكين وحدة مصادقة/مصادقة خدمة التطبيق .
منح الوصول الأمامي للاتصال بـ Microsoft Graph
الآن بعد أن قمت بتمكين المصادقة والتخويل على تطبيق الويب الخاص بك، يتم تسجيل تطبيق الويب مع النظام الأساسي للهويات في Microsoft ويتم دعمه بواسطة تطبيق Microsoft Entra. في هذه الخطوة، يمكنك منح أذونات تطبيق الويب للوصول إلى Microsoft Graph للمستخدم. (من الناحية الفنية، تمنح تطبيق Microsoft Entra لتطبيق الويب أذونات الوصول إلى تطبيق Microsoft Graph Microsoft Entra للمستخدم.)
في مركز إدارة Microsoft Entra، حدد Applications.
حدد تسجيلات التطبيق > التطبيقات المملوكة > عرض جميع التطبيقات في هذا الدليل . حدد اسم تطبيق الويب، ثم حدد أذونات واجهة برمجة التطبيقات.
حدد إضافة إذن، ثم حدد واجهات برمجة تطبيقات Microsoft وMicrosoft Graph.
حدد الأذونات المفوضة، ثم حدد User.Read من القائمة. حدد إضافة أذونات.
تكوين خدمة التطبيقات لإرجاع رمز مميز للوصول قابل للاستخدام
يحتوي تطبيق الويب الآن على الأذونات المطلوبة للوصول إلى Microsoft Graph كمستخدم بتسجيل الدخول. في هذه الخطوة، يمكنك تكوين مصادقة خدمة التطبيقات والتخويل لمنحك رمز وصول قابلاً للاستخدام للوصول إلى Microsoft Graph. لهذه الخطوة، تحتاج إلى إضافة نطاق المستخدم. اقرأ نطاق خدمة المتلقين للمعلومات (Microsoft Graph): https://graph.microsoft.com/User.Read.
هام
إذا لم تقم بتكوين App Service لإرجاع رمز وصول قابل للاستخدام، فستتلقى خطأ CompactToken parsing failed with error code: 80049217 عند استدعاء واجهات برمجة تطبيقات Microsoft Graph في التعليمات البرمجية الخاصة بك.
انتقل إلى Azure Resource Explorer واستخدام شجرة الموارد، وحدد موقع تطبيق الويب الخاص بك. يجب أن يكون عنوان URL للمورد مشابها ل https://resources.azure.com/subscriptions/subscriptionId/resourceGroups/SecureWebApp/providers/Microsoft.Web/sites/SecureWebApp20200915115914.
يتم الآن فتح مستكشف موارد Azure مع تحديد تطبيق الويب في شجرة الموارد.
في أعلى الصفحة، حدد قراءة/كتابة لتمكين تحرير موارد Azure.
في المستعرض الأيسر، انتقل لأسفل لتكوين >authsettingsV2.
في طريقة العرض authsettingsV2 ، حدد Edit.
ابحث عن قسم تسجيل الدخول في identityProviders ->azureActiveDirectory وأضف إعدادات loginParameters التالية:
"loginParameters":[ "response_type=code id_token","scope=openid offline_access profile https://graph.microsoft.com/User.Read" ]."identityProviders": { "azureActiveDirectory": { "enabled": true, "login": { "loginParameters":[ "response_type=code id_token", "scope=openid offline_access profile https://graph.microsoft.com/User.Read" ] } } } },احفظ إعداداتك عن طريق تحديد PUT. قد يستغرق هذا الإعداد عدة دقائق حتى يصبح نافذ المفعول. تم تكوين تطبيق الويب الخاص بك الآن للوصول إلى Microsoft Graph باستخدام رمز مميز للوصول الصحيح. إذا لم تقم بذلك، Microsoft Graph سيقوم بإرجاع خطأ قائلاً إن تنسيق الرمز المميز المضغوط غير صحيح.
اتصل بـ Microsoft Graph مع .NET
يحتوي تطبيق الويب الآن على الأذونات المطلوبة ويضيف أيضًا معرف عميل Microsoft Graph إلى معلمات تسجيل الدخول.
باستخدام مكتبة Microsoft.Identity.Web، يحصل تطبيق الويب على رمز مميز للوصول للمصادقة باستخدام Microsoft Graph. في الإصدار 1.2.0 والإصدارات الأحدث، تتكامل مكتبة Microsoft.Identity.Web مع الوحدة النمطية مصادقة/تخويل خدمة التطبيقات ويمكن تشغيلها جنبًا إلى جنب معها. Microsoft.Identity.Web بالكشف عن أن تتم استضافة تطبيق ويب في خدمة التطبيقات والحصول على رمز الوصول من وحدة مصادقة/تخويل خدمة التطبيق. ثم يتم تمرير الرمز المميز للوصول إلى طلبات مصادق عليها مع واجهة برمجة تطبيقات Microsoft Graph API.
لرؤية هذا التعليمة البرمجية كجزء من نموذج تطبيق، راجع:
إشعار
مكتبة Microsoft.Identity.Web غير مطلوبة في تطبيق الويب الخاص بك للمصادقة/التخويل الأساسي أو لمصادقة الطلبات مع Microsoft Graph. من الممكن استدعاء واجهات برمجة التطبيقات المتلقية للمعلومات بأمان مع تمكين وحدة مصادقة/تخويل App Service فقط.
ومع ذلك، تم تصميم مصادقة/تخويل خدمة التطبيقات لسيناريوهات المصادقة الأساسية. بالنسبة للسيناريوهات الأكثر تعقيدا (معالجة المطالبات المخصصة، على سبيل المثال)، تحتاج إلى مكتبة Microsoft.Identity.Web أو مكتبة مصادقة Microsoft. هناك المزيد من أعمال الإعداد والتكوين في البداية، ولكن يمكن تشغيل مكتبة Microsoft.Identity.Web جنبًا إلى جنب مع وحدة مصادقة/تخويل خدمة التطبيقات. في وقت لاحق، عندما يحتاج تطبيق الويب الخاص بك إلى معالجة سيناريوهات أكثر تعقيدا، يمكنك تعطيل وحدة مصادقة/تخويل خدمة التطبيقات وستكون Microsoft.Identity.Web بالفعل جزءًا من التطبيق.
تثبيت حزم مكتبة العميل
قم بتثبيت حزم Microsoft.Identity.Web وMicrosoft.Identity.Web.MicrosoftGraph NuGet في مشروعك باستخدام واجهة سطر الأوامر .NET Core أو وحدة تحكم مدير الحِزَم في Visual Studio.
سطر الأوامر .NET Core
افتح سطر أوامر، وقم بالتبديل إلى الدليل الذي يحتوي على ملف المشروع الخاص بك.
قوموا بتشغيل أوامر التثبيت.
dotnet add package Microsoft.Identity.Web.MicrosoftGraph
dotnet add package Microsoft.Identity.Web
وحدة تحكم مدير الحزم
افتح المشروع / الحل في Visual Studio، وافتح وحدة التحكم باستخدام الأمر Tools > NuGet Package Manager > Package Manager Console .
قوموا بتشغيل أوامر التثبيت.
Install-Package Microsoft.Identity.Web.GraphServiceClient
Install-Package Microsoft.Identity.Web
Startup.cs
في ملف Startup.cs ، AddMicrosoftIdentityWebApp يضيف الأسلوب Microsoft.Identity.Web إلى تطبيق الويب الخاص بك. AddMicrosoftGraph يضيف الأسلوب دعم Microsoft Graph. للحصول على معلومات حول إدارة الموافقة التزايدية والوصول المشروط، اقرأ هذا.
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Identity.Web;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
// Some code omitted for brevity.
public class Startup
{
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddOptions();
string[] initialScopes = Configuration.GetValue<string>("DownstreamApi:Scopes")?.Split(' ');
services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
.AddMicrosoftIdentityWebApp(Configuration.GetSection("AzureAd"))
.EnableTokenAcquisitionToCallDownstreamApi(initialScopes)
.AddMicrosoftGraph(Configuration.GetSection("DownstreamApi"))
.AddInMemoryTokenCaches();
services.AddAuthorization(options =>
{
// By default, all incoming requests will be authorized according to the default policy
options.FallbackPolicy = options.DefaultPolicy;
});
services.AddRazorPages()
.AddMvcOptions(options => {})
.AddMicrosoftIdentityUI();
services.AddControllersWithViews()
.AddMicrosoftIdentityUI();
}
}
appsettings.json
يحدد AzureAd التكوين لمكتبة Microsoft.Identity.Web. في مركز إدارة Microsoft Entra، حدد Applications من قائمة المدخل ثم حدد App registrations. حدد تسجيل التطبيق الذي تم إنشاؤه عند تمكين وحدة مصادقة/تخويل خدمة التطبيقات. (يجب أن يكون لتسجيل التطبيق نفس اسم تطبيق الويب الخاص بك.) يمكنك العثور على معرف المستأجر ومعرف العميل في صفحة نظرة عامة على تسجيل التطبيق. يمكن العثور على اسم المجال في صفحة نظرة عامة على Microsoft Entra للمستأجر الخاص بك.
يحدد الرسم البياني نقطة نهاية Microsoft Graph والنطاقات الأولية التي يحتاجها التطبيق.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "[Enter the domain of your tenant, e.g. contoso.onmicrosoft.com]",
"TenantId": "[Enter 'common', or 'organizations' or the Tenant Id (Obtained from the Microsoft Entra admin center. Select 'Endpoints' from the 'App registrations' blade and use the GUID in any of the URLs), e.g. da41245a5-11b3-996c-00a8-4d99re19f292]",
"ClientId": "[Enter the Client Id (Application ID obtained from the Microsoft Entra admin center), e.g. ba74781c2-53c2-442a-97c2-3d60re42f403]",
"ClientSecret": "[Copy the client secret added to the app from the Microsoft Entra admin center]",
"ClientCertificates": [
],
// the following is required to handle Continuous Access Evaluation challenges
"ClientCapabilities": [ "cp1" ],
"CallbackPath": "/signin-oidc"
},
"DownstreamApis": {
"MicrosoftGraph": {
// Specify BaseUrl if you want to use Microsoft graph in a national cloud.
// See https://learn.microsoft.com/graph/deployments#microsoft-graph-and-graph-explorer-service-root-endpoints
// "BaseUrl": "https://graph.microsoft.com/v1.0",
// Set RequestAppToken this to "true" if you want to request an application token (to call graph on
// behalf of the application). The scopes will then automatically
// be ['https://graph.microsoft.com/.default'].
// "RequestAppToken": false
// Set Scopes to request (unless you request an app token).
"Scopes": [ "User.Read" ]
// See https://aka.ms/ms-id-web/downstreamApiOptions for all the properties you can set.
}
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
اتصل بـ Microsoft Graph نيابة عن المستخدم
يوضح المثال التالي كيفية الاتصال بـ Microsoft Graph كمستخدم تسجيل الدخول والحصول على بعض معلومات المستخدم. GraphServiceClient يتم إدخال الكائن في وحدة التحكم، وتم تكوين المصادقة لك بواسطة مكتبة Microsoft.Identity.Web.
// Index.cshtml.cs
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Graph;
using System.IO;
using Microsoft.Identity.Web;
using Microsoft.Extensions.Logging;
// Some code omitted for brevity.
[AuthorizeForScopes(Scopes = new[] { "User.Read" })]
public class IndexModel : PageModel
{
private readonly ILogger<IndexModel> _logger;
private readonly GraphServiceClient _graphServiceClient;
public IndexModel(ILogger<IndexModel> logger, GraphServiceClient graphServiceClient)
{
_logger = logger;
_graphServiceClient = graphServiceClient;
}
public async Task OnGetAsync()
{
try
{
var user = await _graphServiceClient.Me.GetAsync();
ViewData["Me"] = user;
ViewData["name"] = user.DisplayName;
using (var photoStream = await _graphServiceClient.Me.Photo.Content.GetAsync())
{
byte[] photoByte = ((MemoryStream)photoStream).ToArray();
ViewData["photo"] = Convert.ToBase64String(photoByte);
}
}
catch (Exception ex)
{
ViewData["photo"] = null;
}
}
}
تنظيف الموارد
إذا أكملت جميع الخطوات في هذا البرنامج التعليمي متعدد الأحزاب، فقد أنشأت App Service وخطة استضافة App Service وحساب تخزين في مجموعة موارد. لقد قمت أيضا بإنشاء تسجيل تطبيق في معرف Microsoft Entra. إذا اخترت تكوينا خارجيا، فربما تكون قد أنشأت مستأجرا خارجيا جديدا. عند عدم الحاجة إلى ذلك، احذف هذه الموارد وتسجيل التطبيق حتى لا تستمر في تحصيل الرسوم.
في هذا البرنامج التعليمي، تتعلم كيفية:
- احذف موارد Azure التي تم إنشاؤها أثناء اتباع البرنامج التعليمي.
لا تحذف مجموعة الموارد
في مدخل Microsoft Azure، حدد Resource groups من قائمة المدخل وحدد مجموعة الموارد التي تحتوي على خطة App Service وApp Service.
حدد حذف مجموعة الموارد لحذف مجموعة الموارد وجميع الموارد.
قد يستغرق تشغيل هذا الأمر عدة دقائق.
حذف تسجيل التطبيق
في مركز إدارة Microsoft Entra، حدد Applications>App registrations. ثم حدد التطبيق الذي قمت بإنشائه.
في نظرة عامة على تسجيل التطبيق، حدد حذف.
حذف المستأجر الخارجي
إذا قمت بإنشاء مستأجر خارجي جديد، يمكنك حذفه. في مركز إدارة Microsoft Entra، استعرض للوصول إلى نظرة عامة على >الهوية>إدارة المستأجرين.
حدد المستأجر الذي تريد حذفه، ثم حدد حذف.
قد تحتاج إلى إكمال الإجراءات المطلوبة قبل أن تتمكن من حذف المستأجر. على سبيل المثال، قد تحتاج إلى حذف جميع تدفقات المستخدم وتسجيلات التطبيق في المستأجر.
إذا كنت جاهزا لحذف المستأجر، فحدد حذف.
الخطوات التالية
في هذا البرنامج التعليمي، نتعلم طريقة القيام بما يأتي:
- منح أذونات مفوضة إلى تطبيق ويب.
- اتصل بـ Microsoft Graph من تطبيق ويب لمستخدم سجل الدخول.
الملاحظات
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجع https://aka.ms/ContentUserFeedback.
إرسال الملاحظات وعرضها المتعلقة بـ