تكوين المصادقة في عينة تطبيق سطح المكتب WPF باستخدام Azure AD B2C

  • مقالة

تستخدم هذه المقالة عينة تطبيق سطح مكتب من إنشاء Windows Presentation Foundation (WPF) لشرح كيفية إضافة مصادقة Azure Active Directory B2C (Azure AD B2C) إلى تطبيقات سطح المكتب لديك.

نظرة عامة

OpenID Connect (OIDC) عبارة عن بروتوكول مصادقة مصمم بناءً على بروتوكول OAuth 2.0. يمكنك استخدام OIDC لتسجيل دخول المستخدمين إلى أحد التطبيقات بشكل آمن. تستخدم عينة تطبيق سطح المكتب هذه منصة Microsoft Authentication Library (MSAL) من خلال تدفق OIDC القائم على استخدام ملحق Proof Key for Code Exchange (PKCE) لحماية رمز المصادقة. إن MSAL عبارة عن مكتبة للتعليمات البرمجية من توفير Microsoft تعمل على تبسيط إضافة دعم المصادقة والتخويل إلى تطبيقات سطح المكتب.

يتضمن تدفق تسجيل الدخول الخطوات التالية:

  1. يفتح المستخدمون التطبيق ويحددون "تسجيل الدخول".
  2. يفتح التطبيق مستعرض النظام في جهاز سطح المكتب ويبدأ تقديم طلب مصادقة إلى Azure AD B2C.
  3. يقوم المستخدمونبالتسجيل أو تسجيل الدخولأوإعادة ضبط كلمة المرورأو تسجيل الدخول باستخدامحساب اجتماعي.
  4. بعد أن ينجح المستخدمون في تسجيل الدخول، يعمل Microsoft Azure Active Directory B2C على إرجاع رمز التخويل إلى التطبيق.
  5. يتخذ التطبيق الإجراءات التالية:
    1. تبديل رمز المصادقة إلى رمز مميز للمعرّف ورمز مميز للوصول ورمز مميز للتحديث.
    2. يقرأ مطالبات الرمز المميز للمعرف.
    3. يقوم بتخزين رمز التحديث في ذاكرة التخزين المؤقتة في الذاكرة لاستخدامه لاحقًا.

تسجيل ملكية التطبيق

لتمكين التطبيق الخاص بك لتسجيل الدخول باستخدام Microsoft Azure Active Directory B2C واستدعاء API ويب، سجل تطبيقين في دليل Microsoft Azure Active Directory B2C.

  • يعمل تسجيل تطبيق سطح المكتب على تمكين التطبيق من تسجيل الدخول باستخدام Azure AD B2C. أثناء تسجيل التطبيق، ستقوم بتحديد URI لإعادة التوجيه. URI إعادة توجيه هي نقطة النهاية التي يتم إعادة توجيه المستخدمين بواسطة Microsoft Azure Active Directory B2C بعد مصادقة مع Microsoft Azure Active Directory B2C. تُنشئ عملية تسجيل التطبيق معرّف التطبيق، المعروف أيضاً باسم معرّف العميل، والذي يعرّف تطبيق سطح المكتب لديك بشكل فريد (على سبيل المثال، معرّف التطبيق: 1).

  • يتيح تسجيلAPI ويبلتطبيقك الاتصال API ويب المحمية. يعرض التسجيل أذونات الوصول واجهة برمجة تطبيقات الويب (النطاقات). تنشئ عملية تسجيل التطبيق معرّف التطبيق، الذي يعرّف بشكل فريد واجهة برمجة تطبيقات الويب (على سبيل المثال، معرّف التطبيق: 2). ويمكنك منح أذونات تطبيق سطح المكتب لديك (معرّف التطبيق: 1) لنطاقات واجهة برمجة تطبيقات الويب (معرّف التطبيق: 2).

عملية تسجيل التطبيق وتصميمه موضحتان في الرسوم التخطيطية التالية:

Diagram of the desktop app with web API, registrations, and tokens.

استدعاء واجهة برمجة تطبيقات الويب

بعد اكتمال المصادقة، يتفاعل المستخدمون مع التطبيق، والذي يستدعي واجهة برمجة تطبيقات ويب محمية. تستخدم واجهة برمجة تطبيقات الويب مصادقة رمز الحامل المميز. رمز الحامل هو الرمز المميز للوصول الذي حصل عليه التطبيق من Microsoft Azure Active Directory B2C. يمرر التطبيق الرمز المميز في رأس التفويض لطلب HTTPS.

Authorization: Bearer <access token>

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

عملية تسجيل الخروج

يتضمن تدفق تسجيل الخروج الخطوات التالية:

  1. من التطبيق، يقوم المستخدمون بتسجيل الخروج.
  2. يمسح التطبيق عناصر الجلسة الخاصة به، وتقوم مكتبة المصادقة بمسح ذاكرة التخزين المؤقت للرمز المميز.
  3. يأخذ التطبيق المستخدمين إلى نقطة نهاية تسجيل الخروج لـ Azure AD B2C لإنهاء جلسة Azure AD B2C.
  4. تتم إعادة توجيه المستخدمين مرة أخرى إلى التطبيق.

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

جهاز كمبيوتر يقوم بتشغيل Visual Studio 2019 باستخدام تطوير سطح المكتب .NET.

الخطوة 1: تكوين تدفق المستخدم الخاص بك

عندما يحاول المستخدمون تسجيل الدخول إلى تطبيقك، يبدأ التطبيق في طلب مصادقة لنقطة نهاية التخويل عبر تدفق المستخدم. يحدد تدفق المستخدم تجربة المستخدم ويتحكم فيها. بعد أن يكمل المستخدمون تدفق المستخدم، ينشئ Azure AD B2C رمزًا مميزًا، ثم يعيد توجيه المستخدم مرةً أخرى إلى تطبيقك.

إذا لم تكن قد قمت بذلك بالفعل، فبادر بإنشاء تدفق مستخدم أو نهج مخصص. كرر الخطوات لإنشاء ثلاثة تدفقات مستخدم منفصلة كما يلي:

  • تسجيل الدخول المشتركة والاشتراك في تدفق المستخدم، مثل susi. يدعم تدفق المستخدم هذا أيضاً تجربة نسيت كلمة المرور الخاصة بك.
  • تدفق تحرير ملف تعريف المستخدم، مثل edit_profile.
  • تدفق إعادة تعيين كلمة مرور المستخدم، مثل reset_password.

يسبق Microsoft Azure AD B2C B2C_1_اسم تدفق المستخدم. على سبيل المثال، يصبح susiB2C_1_susi.

الخطوة 2: تسجيل تطبيقاتك

يجب إنشاء تطبيق سطح المكتب وعملية تسجيل تطبيق واجهة برمجة تطبيقات الويب، ثم تحديد نطاقات واجهة برمجة تطبيقات الويب.

الخطوة 2.1: تسجيل تطبيق الويب API

لإنشاء تسجيل تطبيق واجهة برمجة تطبيقات الويب (App ID: 2)، اتبع الخطوات التالية:

  1. قم بتسجيل الدخول إلى بوابة Azure.

  2. تأكد من استخدام الدليل الذي يحتوي على مستأجر Azure AD B2C. حدّد أيقونة الدلائل + الاشتراكات في شريط أدوات المدخل.

  3. في صفحة Portal settings | Directories + subscriptions ابحث عن دليل Azure AD B2C في قائمة Directory name ثم حدّد Switch.

  4. في مدخل Microsoft Azure، ابحث عن Azure AD B2C وحددها.

  5. حدد App registrations، ثم حدد New registration.

  6. تحت Name، أدخل اسمًا للتطبيق (على سبيل المثال، my-api1). اترك القيم الافتراضية لـ Redirect URIوأنواع الحسابات المدعومة.

  7. حدد تسجيل.

  8. بعد اكتمال عملية تسجيل التطبيق، حدد "Overview".

  9. سجل قيمة Application (client) ID لاستخدامه لاحقًا عند تكوين تطبيق الويب.

    Screenshot that demonstrates how to get a web A P I application I D.

الخطوة 2.2: تكوين نطاقات تطبيقاتAPI على الويب

  1. حدد التطبيق my-api1 الذي أنشأته (App ID: 2) لفتح صفحة Overview الخاصة به.

  2. ضمن إدارة، حدد كشف واجهة برمجة تطبيقات.

  3. بجوار معرف التطبيق URI، حدد رابط تعيين. استبدل القيمة الافتراضية (GUID) باسم فريد (على سبيل المثال، tasks-api) ثم حدد Save.

    عندما يطلب تطبيق الويب الخاص بك رمز وصول لواجهة برمجة تطبيقات الويب، يجب أن يضيف عنوان URI هذا كبادئة لكل نطاق تحدده لواجهة برمجة التطبيقات.

  4. ضمن النطاقات المعرفة من قبل واجهة برمجة التطبيقات API هذه، حدد إضافة نطاق.

  5. لإنشاء نطاق يحدد الوصول للقراءة إلى واجهة برمجة التطبيقات:

    1. بالنسبة إلى اسم النطاق، أدخل المهام.قراءة.
    2. بالنسبة إلى اسم عرض موافقة المسؤول، أدخل قراءة الوصول إلى واجهة برمجة تطبيقات المهام.
    3. بالنسبة إلى وصف موافقة المسؤول، أدخل السماح بالوصول للقراءة إلى واجهة برمجة تطبيقات المهام.

  6. حدد إضافة نطاق.

  7. حدد إضافة نطاق، ثم أضف نطاقًا يحدد حق الوصول للكتابة إلى واجهة برمجة التطبيقات:

    1. بالنسبة إلى اسم النطاق، أدخل features.write.
    2. بالنسبة إلى اسم عرض موافقة المسؤول، أدخل واجهة برمجة تطبيقات الوصول للكتابة إلى المهام.
    3. بالنسبة إلى وصف موافقة المسؤول، أدخل السماح بالوصول للكتابة إلى واجهة برمجة تطبيقات المهام.

  8. حدد إضافة نطاق.

الخطوة 2.3: تسجيل تطبيق سطح المكتب

لإنشاء عملية تسجيل تطبيق سطح المكتب، تولى إجراء ما يلي:

  1. قم بتسجيل الدخول إلى بوابة Azure.
  2. حدد App registrations، ثم حدد New registration.
  3. ضمن "Name"، أدخل اسماً للتطبيق (على سبيل المثال، desktop-app1).
  4. ضمن أنواع الحسابات المدعومة، حدد الحسابات في أي موفر هوية أو دليل تنظيمي (لمصادقة المستخدمين بعمليات سير عمل المستخدمين).
  5. ضمن "URI لإعادة التوجيه"، حدد "عميل عام/أصلي (سطح المكتب وسطح المكتب)" ثم أدخل في مربع عنوان URL https://your-tenant-name.b2clogin.com/oauth2/nativeclient. استبدل your-tenant-name بـ اسم المستأجر لديك. للحصول على مزيد من الخيارات، يمكنك الاطلاع على تكوين URI لإعادة التوجيه.
  6. حدد تسجيل.
  7. بعد اكتمال عملية تسجيل التطبيق، حدد "Overview".
  8. سجّل "معرّف التطبيق (العميل)" لاستخدامه لاحقاً عند تكوين تطبيق سطح المكتب. Screenshot highlighting the desktop application ID.

الخطوة 2.4: منح واجهة برمجة تطبيقات الويب أذونات تطبيق سطح المكتب

لمنح تطبيقك (App ID: 1) أذونات، اتبع الخطوات التالية:

  1. حدد App registrations، ثم حدد التطبيق الذي قمت بإنشائه (معرف التطبيق: 1).

  2. ضمن خانة الإدارة، اختر الأذونات الخاصة بواجهة برمجة التطبيقات.

  3. ضمن أذونات مكونة، حدد إضافة إذن.

  4. حدد علامة التبويب واجهات برمجة التطبيقات الخاصة بي.

  5. حدد واجهة برمجة التطبيقات (App ID: 2) التي يجب منح تطبيق الويب حق الوصول إليها. على سبيل المثال، أدخل my-api1.

  6. ضمن Permission، وسّع المهام، ثم حدد النطاقات التي حددتها سابقًا (على سبيل المثال، tasks.read وtasks.write).

  7. حدد إضافة أذونات.

  8. حدد «منح موافقة المسؤول لـ» <اسم المستأجر الخاص بك>.

  9. حدد نعم.

  10. حدد Refresh، ثم تحقق من ظهور منح لـ ... ضمن Status لكلا النطاقين.

  11. من قائمة Configured permissions، حدد النطاق الخاص بك، ثم انسخ الاسم الكامل للنطاق.

    Screenshot of the configured permissions pane, showing that read access permissions are granted.

الخطوة 3: تكوين عينة واجهة برمجة تطبيقات الويب

تحصل هذه العينة على الرمز المميز للوصول مع النطاقات ذات الصلة التي يمكن أن يستخدمها تطبيق سطح المكتب لإحدى واجهات برمجة تطبيقات الويب. للاتصال API ويب من التعليمات البرمجية، قم بما يلي:

  1. استخدم واجهة برمجة تطبيقات الويب الحالية أو قم بإنشاء واجهة جديدة. للحصول على مزيدٍ من المعلومات، يمكنك الاطلاع على تمكين المصادقة في واجهة برمجة تطبيقات الويب الخاصة لديك باستخدام Azure AD B2C.
  2. بعد تكوين واجهة برمجة تطبيقات الويب، انسخ URI الخاص بنقطة نهاية الواجهة. ستستخدم نقطة نهاية واجهة برمجة تطبيقات الويب في الخطوات التالية.

تلميح

إذا لم تكن لديك واجهة لبرمجة تطبيقات الويب، فلا يزال بإمكانك تشغيل هذه العينة. في هذه الحالة، يتولى التطبيق إرجاع الرمز المميز للوصول، لكنه لن يتمكن من استدعاء واجهة برمجة تطبيقات الويب.

الخطوة 4: الحصول على عينة تطبيق سطح المكتب من إنشاء WPF

  1. بادر بتنزيل ملف .zip أو نسخ عينة تطبيق الويب من مستودع GitHub.

    git clone https://github.com/Azure-Samples/active-directory-b2c-dotnet-desktop.git

  2. افتح الحل "active-directory-b2c-wpf" (ملف active-directory-b2c-wpf.sln) في Visual Studio.

الخطوة 5: تكوين عينة تطبيق سطح المكتب

في المشروع "active-directory-b2c-wpf" افتح الملف "App.xaml.cs". يحتوي أعضاء فئة App.xaml.cs على معلومات حول موفر هوية Azure AD B2C لديك. يستخدم تطبيق سطح المكتب هذه المعلومات لإنشاء علاقة ثقة مع Azure AD B2C، وتسجيل دخول المستخدمين وخروجهم، والحصول على الرموز المميزة، والتحقق من صحتها.

تحديث أعضاء الفئة التالين:

مفتاح القيمة
TenantName الجزء الأول من اسم مستأجر Microsoft Azure Active Directory B2C (على سبيل المثال، contoso.b2clogin.com).
ClientId معرّف تطبيق سطح المكتب من الخطوة 2.3.
PolicySignUpSignIn تدفق المستخدم للتسجيل أو تسجيل الدخول أو النهج المخصص الذي أنشأته في الخطوة 1.
PolicyEditProfile تدفق المستخدم لتحرير ملف التعريف أو النهج المخصص الذي أنشأته في الخطوة 1.
ApiEndpoint (اختياري) نقطة نهاية واجهة برمجة تطبيقات الويب التي أنشأتها في الخطوة 3 (على سبيل المثال، https://contoso.azurewebsites.net/hello).
ApiScopes نطاقات واجهة برمجة تطبيقات الويب التي أنشأتها في الخطوة 2.4.

يجب أن يبدو ملفك النهائي App.xaml.cs على هيئة التعليمة البرمجية C# التالية:

public partial class App : Application
{

private static readonly string TenantName = "contoso";
private static readonly string Tenant = $"{TenantName}.onmicrosoft.com";
private static readonly string AzureAdB2CHostname = $"{TenantName}.b2clogin.com";
private static readonly string ClientId = "<web-api-app-application-id>";
private static readonly string RedirectUri = $"https://{TenantName}.b2clogin.com/oauth2/nativeclient";

public static string PolicySignUpSignIn = "b2c_1_susi";
public static string PolicyEditProfile = "b2c_1_edit_profile";
public static string PolicyResetPassword = "b2c_1_reset";

public static string[] ApiScopes = { $"https://{Tenant}//api/tasks.read" };
public static string ApiEndpoint = "https://contoso.azurewebsites.net/hello";

الخطوة 6: تشغيل تطبيق سطح المكتب واختباره

  1. استعادة حزم NuGet.

  2. حدد F5 لتحويل العينة برمجياً وتشغيلها.

  3. حدد "Sign In" ثم قم بالتسجيل أو تسجيل الدخول باستخدام حسابك المحلي أو الاجتماعي في Azure AD B2C.

    Screenshot highlighting how to start the sign-in flow.

  4. بعد التسجيل أو تسجيل الدخول بنجاح، تظهر تفاصيل الرمز المميز في الجزء السفلي من تطبيق WPF.

    Screenshot highlighting the Azure AD B2C access token and user ID.

  5. حدد "استدعاء واجهة برمجة التطبيقات" لاستدعاء واجهة برمجة تطبيقات الويب لديك.

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

تعرف على كيفية تكوين خيارات المصادقة في تطبيق سطح مكتب من إنشاء WPF باستخدام Azure AD B2C.