قم بتكوين المصادقة في نموذج تطبيق ويب يستدعي واجهة برمجة تطبيقات API الويب باستخدام Azure AD B2C

  • مقالة

تستخدم هذه المقالة نموذجًا لتطبيق ويب ASP.NET يستدعي واجهة برمجة تطبيقات الويب API لتوضيح كيفية إضافة مصادقة Azure Active Directory B2C (Azure AD B2C) إلى تطبيقات الويب الخاصة بك.

هام

يتم استخدام نموذج تطبيق الويب ASP.NET المشار إليه في هذه المقالة لاستدعاء واجهة برمجة تطبيقات الويب API باستخدام رمز حامل مميز. للحصول على تطبيق ويب لا يستدعي واجهة برمجة تطبيقات الويب، راجع تكوين المصادقة في نموذج تطبيق ويب باستخدام Azure AD B2C.

نظرة عامة

OID الاتصال (OIDC) هو بروتوكول مصادقة مبني على OAuth 2.0. يمكنك استخدام OIDC لتسجيل دخول المستخدم بأمان إلى أحد التطبيقات. يستخدم نموذج تطبيق الويب هذا Microsoft Identity Web. Microsoft Identity Web عبارة عن مجموعة من مكتبات ASP.NET Core تعمل على تبسيط إضافة المصادقة ودعم التخويل لتطبيقات الويب التي يمكنها استدعاء واجهة برمجة تطبيقات الويب الآمنة.

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

  1. يقوم المستخدمون بالانتقال إلى تطبيق الويب وتحديدتسجيل الدخول.

  2. يبدأ التطبيق طلب مصادقة ويعيد توجيه المستخدمين إلىAzure AD B2C.

  3. يقوم المستخدمون بالتسجيل أو تسجيل الدخول وإعادة تعيين كلمة المرور. بدلا من ذلك، يمكنهم تسجيل الدخول باستخدام حساب اجتماعي.

  4. بعد أن يقوم المستخدمون بتسجيل الدخول، يقومAzure AD B2C بإرجاع رمز المصادقة إلى التطبيق.

  5. ثم يقوم التطبيق بما يلي:

    أ. تبديل رمز المصادقة إلى رمز مميز للمعرّف ورمز مميز للوصول ورمز مميز للتحديث.
    ب. يقرأ مطالبات الرمز المميز للمعرف، ويستمر في ملف تعريف ارتباط ترخيص التطبيق.
    جـ. يقوم بتخزين رمز التحديث في ذاكرة التخزين المؤقت في الذاكرة لاستخدامه لاحقًا.

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

لتمكين تطبيقك من تسجيل الدخول باستخدام Azure AD B2C واستدعاء واجهة برمجة تطبيقات الويب، يمكنك تسجيل تطبيقين في دليل Azure AD B2C.

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

  • يمكّن تسجيل واجهة برمجة تطبيقات الويب تطبيقك من استدعاء واجهة برمجة تطبيقات ويب آمنة. يتضمن التسجيل نطاقات واجهة برمجة تطبيقات الويب. توفر النطاقات طريقة لإدارة أذونات الموارد المحمية، مثل واجهة برمجة تطبيقات الويب API. أنت تمنح أذونات تطبيق الويب لنطاقات واجهة برمجة تطبيقات الويب API. عند طلب رمز وصول، يحدد التطبيق الأذونات المطلوبة في معلمة النطاق الخاصة بالطلب.

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

Diagram of a web app with web API call registrations and tokens.

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

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

Authorization: Bearer <access token>

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

«Sign-out»

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

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

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

جهاز كمبيوتر يعمل إما:

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

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

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

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

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

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

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

الخطوة 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. حدد App registrations، ثم حدد New registration.

  2. ضمنالاسم، أدخل اسمًا للتطبيق (على سبيل المثال، webapp1).

  3. ضمن أنواع الحسابات المدعومة، حدد الحسابات في أي موفر هوية أو دليل تنظيمي (لمصادقة المستخدمين بعمليات سير عمل المستخدمين).

  4. بمقتضىRedirect URI، حددويب، ثم أدخلhttps://localhost:5000/signin-oidcفي المربع النصي لعنوان URL.

  5. ضمنأذونات الوصول، حدد مربع الاختيارلمنح موافقة المسؤول لفتح أذونات دخول والوصول عند عدم الاتصال بالإنترنت.

  6. حدد تسجيل.

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

  8. سجّلمعرف التطبيق (لكمبيوتر العميل) لاستخدامه لاحقًا عند تكوين تطبيق الويب.

    Screenshot of the web app Overview page for recording your web application ID.

الخطوة 2.4: إنشاء سر عميل تطبيق الويب

إنشاء سر عميل لتطبيق الويب المسجل. يستخدم تطبيق الويب سر العميل لإثبات هويته عندما يطلب الرموز.

  1. ضمن "Manage"، حدد "Certificates & secrets".
  2. حدد سر عميل جديد.
  3. في مربع Description، أدخل وصفاً لسر العميل (على سبيل المثال، clientsecret1).
  4. من Expires ، حدد مدة صلاحية السر، ثم حدد Add .
  5. سجّل قيمةالسر. ستستخدم هذه القيمة للتكوين في خطوة لاحقة.

الخطوة 2.5: امنح أذونات تطبيق الويب لواجهة برمجة تطبيقات الويب API

لمنح تطبيقك (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: احصل على نموذج تطبيق الويب

قم بتنزيل الملف المضغوط، أو قم بتشغيل أمر Bash التالي لاستنساخ نموذج تطبيق الويب من GitHub.

git clone https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2

استخراج عينة الملف إلى مجلد حيث الطول الإجمالي للمسار هو 260 حرفًا أو أقل.

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

في المجلد النموذجي، في المجلد 4-WebApp-your-API/4-2-B2C/TodoListService ، افتح مشروع TodoListService.csproj باستخدام Visual Studio أو Visual Studio Code.

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

المقطع مفتاح القيمة
AzureAdB2C ‏‏مثيل الجزء الأول من اسم مستأجر متاجرة عمل-مستهلك في Azure Active Directory. على سبيل المثال، https://contoso.b2clogin.com
AzureAdB2C النطاق اسم المستأجر الكامل لمستأجر Azure AD B2C. على سبيل المثال، contoso.onmicrosoft.com
AzureAdB2C ClientId معرّف تطبيق واجهة برمجة تطبيقات الويب من الخطوة 2.1.
AzureAdB2C SignUpSignInPolicyId يتدفق المستخدم أو النهج المخصص الذي أنشأته في الخطوة 1.

يجب أن يبدو ملف التكوين النهائي الخاص بك مثل ملف JSON التالي:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-api-app-application-id>",
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  // More settings here
}

الخطوة 4.1: تعيين سياسة الأذونات

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

لتكوين النطاقات المقبولة، افتح فئة Controller/TodoListController.cs، وقم بتعيين اسم النطاق، بدون URI الكامل.

[RequiredScope("tasks.read")]

الخطوة 4.2: قم بتشغيل نموذج تطبيق Web API

للسماح لتطبيق الويب باستدعاء نموذج واجهة برمجة تطبيقات الويب، قم بتشغيل واجهة برمجة تطبيقات الويب عن طريق القيام بما يلي:

  1. إذا طُلب منك القيام بذلك، قم باستعادة التبعيات.
  2. بناء وتشغيل المشروع.
  3. بعد بناء المشروع، يبدأ Visual Studio أو Visual Studio Code واجهة برمجة تطبيقات الويب في المستعرضات بالعنوان التالي: https://localhost:44332.

الخطوة 5: تكوين نموذج تطبيق الويب

في المجلد النموذج ضمن 4-WebApp-your-API/4-2-B2C/Client المجلد، افتح المشروع TodoListClient.csproj باستخدام Visual Studio أو Visual Studio Code.

ضمن المجلد الجذر للمشروع، افتح الملف appsettings.json. يحتوي هذا الملف على معلومات حول موفر الهوية Microsoft Azure AD B2C. يستخدم تطبيق الويب هذه المعلومات لإنشاء علاقة ثقة معAzure AD B2C، وتسجيل دخول المستخدمين وخروجهم، والحصول على الرموز المميزة، والتحقق من صحتها. قم بتحديث الخصائص التالية لإعدادات التطبيق:

المقطع مفتاح القيمة
AzureAdB2C ‏‏مثيل الجزء الأول من اسم مستأجر Microsoft Azure Active Directory B2C (على سبيل المثال، https://contoso.b2clogin.com).
AzureAdB2C النطاق مستأجر خدمات مجال Microsoft Azure Active Directory B2C اسم المستأجر بالكامل (على سبيل المثال، contoso.onmicrosoft.com).
AzureAdB2C ClientId معرف تطبيق الويب من الخطوة 2.3.
AzureAdB2C ClientSecret سر تطبيق الويب من الخطوة 2.4.
AzureAdB2C SignUpSignInPolicyId تدفقات المستخدم، أو السياسة المخصصة التي أنشأتها فيالخطوة 1.
عمل قائمة TodoListScope نطاقات واجهة برمجة تطبيقات الويب التي أنشأتها في الخطوة 2.5.
عمل قائمة TodoListBaseAddress URI الأساسي لواجهة برمجة تطبيقات الويب (على سبيل المثال https://localhost:44332).

ينبغي أن يبدو ملف التكوين النهائي مثل JSON التالي:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-app-application-id>",
    "ClientSecret": "<web-app-application-secret>",  
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  "TodoList": {
    "TodoListScope": "https://contoso.onmicrosoft.com/api/demo.read",
    "TodoListBaseAddress": "https://localhost:44332"
  }
}

الخطوة 6: قم بتشغيل نموذج تطبيق الويب

  1. بناء وتشغيل المشروع.
  2. استعرض إلى https://localhost:5000.
  3. قم بإكمال عملية التسجيل أو تسجيل الدخول.

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

Screenshot of the web app token claims.

نشر تطبيقك

في تطبيق الإنتاج، عادة ما يكون عنوان URI لإعادة توجيه تسجيل التطبيق نقطة نهاية يمكن الوصول إليها بشكل عام حيث يتم تشغيل تطبيقك، مثل https://contoso.com/signin-oidc.

يمكنك إضافة وتعديل عناوين "URI" لإعادة التوجيه في تطبيقاتك المسجلة في أي وقت. تنطبق القيود التالية على إعادة توجيه عناوين "URI":

  • يجب أن يبدأ عنوان URL للرد بنظام https.
  • يكون عنوان "URL" للرد حساسًا لحالة الأحرف. يجب أن تتطابق حالته مع حالة مسار عنوان "URL" للتطبيق قيد التشغيل.

رمز ذاكرة التخزين المؤقت لتطبيق ويب

يستخدم نموذج تطبيق الويب تسلسل ذاكرة التخزين المؤقت للرمز المميز في الذاكرة. هذا التنفيذ رائع في العينات. إنها أيضًا جيدة في تطبيقات الإنتاج، بشرط ألا تمانع في فقدان ذاكرة التخزين المؤقت للرمز المميز عند إعادة تشغيل تطبيق الويب.

لبيئة الإنتاج، نوصي باستخدام ذاكرة تخزين مؤقت موزعة. على سبيل المثال، ذاكرة التخزين المؤقت Redis أو NCache أو ذاكرة التخزين المؤقت لـ SQL Server. للحصول على تفاصيل حول عمليات تنفيذ ذاكرة التخزين المؤقت للذاكرة الموزعة، راجع تسلسل ذاكرة التخزين المؤقت للرمز المميز.

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