البرنامج التعليمي: إنشاء برنامج خفي متعدد المستأجرين يستخدم النظام الأساسي للهويات في Microsoft

في هذا البرنامج التعليمي، يمكنك تنزيل وتشغيل تطبيق ويب ASP.NET الخفي الذي يوضح استخدام بيانات اعتماد عميل OAuth 2.0 للحصول على رمز الوصول المميز لاستدعاء واجهة برمجة تطبيقات Microsoft Graph.

سوف تتعلم في هذا البرنامج التعليمي:

  • دمج التطبيق الخفي مع النظام الأساسي للهويات في Microsoft
  • منح أذونات التطبيق مباشرة إلى التطبيق من قِبل المسؤول
  • الحصول على رمز الوصول المميز لاستدعاء واجهة برمجة تطبيقات Microsoft Graph
  • استدعاء واجهة برمجة تطبيقات Microsoft Graph.

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

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

  • Visual Studio 2017 أو 2019.
  • مستأجر AAD (دليل Azure النشط). لمزيد من المعلومات، يرجى الرجوع إلى كيفية الحصول على مستأجر Azure AD.
  • حساب مستخدم واحد أو أكثر في مستأجر Azure AD. لن يعمل هذا النموذج مع حساب Microsoft. إذا قمت بتسجيل الدخول إلى مدخل Azure باستخدام حساب Microsoft ولم تقم مطلقاً بإنشاء حساب مستخدم في دليلك، فافعل ذلك الآن.

السيناريو

تم بناء التطبيق كتطبيق ASP.NET MVC. يستخدم البرنامج الوسيط OWIN OpenID Connect لتسجيل دخول المستخدمين.

مكون "البرنامج الخفي" في هذا النموذج هو وحدة تحكم API، SyncController.cs. عند استدعاء وحدة التحكم، فإنها تسحب قائمة المستخدمين في مستأجر Azure Active Directory (Azure AD) الخاص بالعميل من Microsoft Graph. SyncController.cs يتم تشغيلها بواسطة استدعاء AJAX في تطبيق الويب. يستخدم مكتبة مصادقة Microsoft (MSAL) لـ .NET للحصول على رمز الوصول المميز لـ Microsoft Graph.

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

Diagram shows UserSync App with three local items connecting to Azure, with Start dot Auth acquiring a token interactively to connect to Azure A D, AccountController getting admin consent to connect to Azure A D, and SyncController reading user to connect to Microsoft Graph.

لمزيد من المعلومات حول المفاهيم المستخدمة في هذا النموذج، يرجى قراءة وثائق بروتوكول بيانات اعتماد العميل للنظام الأساسي للهوية.

استنساخ أو تنزيل هذا المستودع

من shell أو سطر الأوامر، أدخل هذا الأمر:

git clone https://github.com/Azure-Samples/active-directory-dotnet-daemon-v2.git

أو قم بتنزيل النموذج في ملف مضغوط.

تسجيل طلبك

يحتوي هذا النموذج على مشروع واحد. لتسجيل التطبيق مع مستأجر Azure AD، يمكنك إما:

إذا كنت ترغب في استخدام التنفيذ التلقائي:

  1. قم بتشغيل PowerShell على Windows، ثم انتقل إلى جذر الدليل المستنسخ.

  2. قم بتشغيل هذا الأمر:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
    
  3. تشغيل البرنامج النصي لإنشاء تطبيق Azure AD وتكوين التعليمات البرمجية للتطبيق النموذج وفقاً لذلك:

    .\AppCreationScripts\Configure.ps1
    

    تم وصف الطرق الأخرى لتشغيل النصوص البرمجية في البرامج النصية لإنشاء التطبيق.

  4. افتح الحل Visual Studio وحدد "Start" لتشغيل التعليمات البرمجية.

إذا كنت لا تريد استخدام التنفيذ التلقائي، فاستخدم الخطوات الواردة في الأقسام التالية.

اختر مستأجر Azure AD

  1. تسجيل الدخول إلى ⁧⁩مدخل Azure⁧⁩.
  2. إذا كان لديك حق الوصول إلى عدة مستأجرين، فاستخدم عامل تصفية Directories + subscriptions في القائمة العلوية للتبديل إلى المستأجر الذي تريد تسجيل التطبيق فيه.

تسجيل التطبيق العميل (dotnet-web-daemon-v2)

  1. ابحث عن Azure Active Directory ثم حدده.

  2. ضمن Manage، حدد App registrationsتسجيل >جديد.

  3. أدخل ⁧⁩"Name"⁧⁩ للتطبيق، على سبيل المثال⁧dotnet-web-daemon-v2⁩. قد يرى مستخدمو تطبيقك هذا الاسم، ويمكنك تغييره لاحقاً.

  4. في القسم "Supported account types" ، حدد "Accounts in any organizational directory" .

  5. في القسم "Redirect URI" (اختياري) ، حدد "Web" في مربع التحرير والسرد وأدخل https://localhost:44316/ وhttps://localhost:44316/Account/GrantPermissions كعناوين URL لإعادة التوجيه.

    إذا كان هناك أكثر من عنواني URI لإعادة التوجيه، فستحتاج إلى إضافتها من علامة التبويب "Authentication" لاحقاً، بعد إنشاء التطبيق بنجاح.

  6. حدد Register لإنشاء التطبيق.

  7. في صفحة "Overview" للتطبيق، ابحث عن قيمة Application (client) ID وسجله للاستخدام لاحقاً. ستحتاج إلى تكوين ملف تكوين Visual Studio لهذا المشروع.

  8. ضمن "Manage"، حدد "Authentication".

  9. قم بتعيين "Front-channel logout URL" إلى https://localhost:44316/Account/EndSession.

  10. في قسم "Implicit grant and hybrid flows" ، حدد "Access tokens" وحدد "ID tokens" . يتطلب هذا النموذج تمكين "implicit grant flow" لتسجيل دخول المستخدم واستدعاء واجهة برمجة التطبيقات.

  11. حدد ⁧⁩حفظ⁧⁩.

  12. ضمن إدارة، حدد الشهادات&الأسرار.

  13. في قسم ⁧⁩"Client secrets"⁧⁩، حدد ⁧⁩"New client secret"⁧⁩.

  14. أدخل وصفاً رئيسياً (على سبيل المثال، سر التطبيق).

  15. حدد مدة رئيسية إما خلال عام واحد، وإما خلال عامين، وإما لا تنتهي الصلاحية أبداً.

  16. حدد ⁧⁩إضافة⁧⁩. سجل قيمة المفتاح في موقع آمن. ستحتاج إلى هذا المفتاح لاحقاً لتكوين المشروع في Visual Studio.

  17. ضمن "Manage" ، حدد API permissions>Add a permission.

  18. في القسم "Commonly used Microsoft APIs" ، حدد "Microsoft Graph" .

  19. في القسم "Application permissions" ، تأكد من تحديد الأذونات الصحيحة: "User.Read.All" .

  20. حدد "Add permissions".

تكوين النموذج لاستخدام مستأجر Azure AD

في الخطوات التالية، سيكون ClientID هو نفسه "معرف التطبيق" أو AppId.

افتح الحل في Visual Studio لتكوين المشاريع.

تكوين مشروع العميل

إذا استخدمت البرامج النصية للإعداد، فسيتم تطبيق التغييرات التالية بالنسبة لك.

  1. افتح الملف UserSync\Web.Config.
  2. ابحث عن مفتاح التطبيق ida:ClientId. استبدل القيمة الحالية بمعرف التطبيق الخاص بتطبيق dotnet-web-daemon-v2 المنسوخ من مدخل Azure.
  3. ابحث عن مفتاح التطبيق ida:ClientSecret. استبدل القيمة الحالية بالمفتاح الذي قمت بحفظه أثناء إنشاء تطبيق dotnet-web-daemon-v2 في مدخل Azure.

تشغيل النموذج

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

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

User consent

يحاول التطبيق بعد ذلك مزامنة قائمة المستخدمين من مستأجر Azure AD، عبر Microsoft Graph. إذا لم يتمكن من ذلك، فإنه يطلب منك (مسؤول المستأجر) توصيل المستأجر الخاص بك بالتطبيق.

ثم يطلب التطبيق إذناً لقراءة قائمة المستخدمين في المستأجر.

Admin consent

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

عند منح الإذن، يمكن للتطبيق الاستعلام عن المستخدمين عند أي نقطة. يمكنك التحقق من ذلك عن طريق تحديد الزر "Sync Users" وتحديث قائمة المستخدمين. حاول إضافة مستخدم أو حذفه وإعادة مزامنة القائمة. (لكن لاحظ أن التطبيق يقوم بمزامنة الصفحة الأولى فقط من المستخدمين.)

حول التعليمات البرمجية

توجد التعليمات البرمجية ذات الصلة لهذا النموذج في الملفات التالية:

  • App_Start\Startup.Auth.cs، Controllers\AccountController.cs: تسجيل الدخول الأولي. وبشكل خاص، فإن الإجراءات على وحدة التحكم لها سمة تفويض، يفرض على المستخدم تسجيل الدخول. يستخدم التطبيق تدفق رمز التفويض لتسجيل دخول المستخدم.
  • Controllers\SyncController.cs: مزامنة قائمة المستخدمين مع مخزن الذاكرة المحلي.
  • Controllers\UserController.cs: عرض قائمة المستخدمين مع مخزن الذاكرة المحلي.
  • Controllers\AccountController.cs: الحصول على أذونات من مسؤول المستأجر باستخدام نقطة نهاية موافقة المسؤول.

إعادة إنشاء نموذج التطبيق

  1. في Visual Studio، قم بإنشاء مشروع جديد Visual C#‎ASP.NET Web Application (.NET Framework) project.
  2. على الشاشة التالية، اختر قالب مشروع MVC. أضف أيضاً المجلد والمراجع الأساسية لواجهة برمجة تطبيقات الويب، لأنك ستضيف وحدة تحكم واجهة برمجة تطبيقات الويب لاحقاً. اترك وضع المصادقة الذي اختاره المشروع كإعداد افتراضي: "No Authentication" .
  3. حدد المشروع في النافذة "Solution Explorer" وحدد المفتاح F4.
  4. في خصائص المشروع، قم بتعيين "SSL Enabled" إلى "True" . لاحظ المعلومات الموجودة في عنوان SSL URL. ستحتاج إليه عند تكوين تسجيل هذا التطبيق في مدخل Azure.
  5. أضف حزم ASP.NET OWIN middleware NuGet التالية:
    • Microsoft.Owin.Security.ActiveDirectory
    • Microsoft.Owin.Security.Cookies
    • Microsoft.Owin.Host.SystemWeb
    • Microsoft.IdentityModel.Protocol.Extensions
    • Microsoft.Owin.Security.OpenIdConnect
    • Microsoft.Identity.Client
  6. في المجلد App_Start:
    1. إنشاء فئة باسم Startup.Auth.cs.
    2. حذف . App_Start من اسم مساحة الاسم.
    3. استبدال التعليمات البرمجية لفئة Startup بالتعليمات البرمجية من نفس ملف التطبيق النموذج. تأكد من أخذ تعريف الفئة بأكملها. يتغير التعريف من public class Startup إلى public partial class Startup.
  7. في Startup.Auth.cs، قم بحل المراجع المفقودة عن طريق إضافة استخدام عبارات كما هو مقترح بواسطة Visual Studio IntelliSense.
  8. انقر بزر الماوس الأيمن فوق المشروع، وحدد "Add" ، ثم حدد "Class" .
  9. في مربع البحث، أدخل OWIN. تظهر فئة OWIN Startup كتحديد. حددها، وامنح الفئة اسم Startup.cs.
  10. في Startup.cs، استبدل التعليمات البرمجية لفئة Startup بالتعليمات البرمجية من نفس ملف التطبيق النموذج. مرة أخرى، لاحظ أن التعريف يتغير من public class Startup إلى public partial class Startup.
  11. في المجلد Models أضف فئة جديدة باسم MsGraphUser.cs. استبدل التطبيق بمحتويات الملف الذي يحمل نفس الاسم من النموذج.
  12. أضف مثيل MVC 5 Controller - Empty جديداً باسم AccountController. استبدل التطبيق بمحتويات الملف الذي يحمل نفس الاسم من النموذج.
  13. أضف مثيل MVC 5 Controller - Empty جديداً باسم UserController. استبدل التطبيق بمحتويات الملف الذي يحمل نفس الاسم من النموذج.
  14. أضف مثيل Web API 2 Controller - Empty جديداً باسم SyncController. استبدل التطبيق بمحتويات الملف الذي يحمل نفس الاسم من النموذج.
  15. بالنسبة لواجهة المستخدم، في المجلد Views\Account، أضف ثلاثة مثيلات Empty (without model) Views باسم GrantPermissions، وIndex، وUserMismatch. أضف واحداً باسم Index في المجلد Views\User. استبدل التطبيق بمحتويات الملف الذي يحمل نفس الاسم من النموذج.
  16. قم بتحديث Shared_Layout.cshtmlو Home\Index.cshtml لربط طرق العرض المختلفة معًا بشكل صحيح.

نشر النموذج إلى Azure

يحتوي هذا المشروع على تطبيق ويب ومشاريع واجهة برمجة تطبيقات ويب. لنشرها في مواقع Azure، اتبع الخطوات التالية لكل منها:

  1. إنشاء موقع Azure على الويب.
  2. نشر تطبيق الويب وواجهات برمجة التطبيقات على الويب إلى موقع الويب.
  3. تحديث العملاء للاتصال بموقع ويب بدلاً من IIS Express.

إنشاء ونشر dotnet-web-daemon-v2 إلى موقع Azure على الويب

  1. قم بتسجيل الدخول إلى مدخل Microsoft Azure
  2. في الزاوية العلوية اليسرى، حدد Create a resource.
  3. حدد Web>Web App، ثم قم بتسمية موقع الويب الخاص بك. على سبيل المثال، أطلق عليها اسم dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. حدد معلومات الاشتراك، ومجموعة الموارد، وخطة خدمة التطبيق وموقعه. سيكون نظام التشغيلWindows، والنشرCode.
  5. حدد "Create" وانتظر حتى يتم إنشاء خدمة التطبيق.
  6. عند تلقي إشعار Deployment succeeded، حدد "Go to resource" للانتقال إلى خدمة التطبيق التي تم إنشاؤها حديثاً.
  7. بعد إنشاء موقع الويب، ابحث عنه في لوحة المعلومات وحدده لفتح شاشة نظرة عامة على خدمة التطبيق.
  8. من علامة التبويب "Overview" في خدمة التطبيق، قم بتنزيل ملف تعريف النشر عن طريق تحديد الرابط "Get publish profile" وحفظه. يمكنك استخدام آليات نشر أخرى، مثل النشر من عنصر التحكم بالمصدر.
  9. التبديل إلى Visual Studio ثم:
    1. انتقل إلى مشروع dotnet-web-daemon-v2.
    2. انقر بزر الماوس الأيمن فوق المشروع في "Solution Explorer"، وحدد "Publish" .
    3. حدد "Import Profile" في الشريط السفلي، واستورد ملف تعريف النشر الذي قمت بتنزيله سابقاً.
  10. حدد ⁧⁩Configure⁧⁩.
  11. في علامة التبويب «اتصال»، قم بتحديث عنوان URL المقصود بحيث يستخدم «https»علي سبيل المثال https://dotnet-web-daemon-v2-contoso.azurewebsites.net. حدد "Next".
  12. في علامة التبويب "Settings" ، تأكد من مسح Enable Organizational Authentication.
  13. حدد ⁧⁩حفظ⁧⁩. حدد "Publish" على الشاشة الرئيسية.

سينشر Visual Studio المشروع ويفتح تلقائياً متصفحاً لعنوان URL الخاص بالمشروع. إذا رأيت صفحة الويب الافتراضية للمشروع، فهذا يعني نجاح النشر.

تحديث تسجيل تطبيق مستأجر Azure AD لـ dotnet-web-daemon-v2

  1. ارجع إلى مدخل Azure.
  2. في الجزء الأيسر، حدد خدمة Azure Active Directory، ثم حدد "App registrations" .
  3. حدد تطبيق dotnet-web-daemon-v2.
  4. في صفحة "Authentication" للتطبيق الخاص بك، قم بتحديث حقول "Front-channel logout URL" بعنوان الخدمة. على سبيل المثال، استخدم https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession.
  5. من القائمة "Branding" ، قم بتحديث "Home page URL" إلى عنوان الخدمة. على سبيل المثال، استخدم https://dotnet-web-daemon-v2-contoso.azurewebsites.net.
  6. Save the configuration.
  7. أضف عنوان URL نفسه في قائمة قيم القائمة Authentication>Redirect URIs. إذا كانت لديك عدة عناوين URL لإعادة التوجيه، فتأكد من وجود إدخال جديد يستخدم URI لخدمة التطبيق لكل عنوان URL لإعادة التوجيه.

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

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

الحصول على المساعدة

استخدم Microsoft Q& A للحصول على الدعم من المجتمع. قم بطرح أسئلتك على Microsoft Q&Aأولاً، ثم تصفح المشكلات الموجودة لمعرفة ما إذا كان هناك شخص ما قد طرح سؤالك من قبل. تأكد من وضع علامات على أسئلتك أو تعليقاتك باستخدام "azure-ad-adal-depecation" و"azure-ad-msal" و"dotnet-standard."

إذا وجدت خطأ في النموذج، فيرجى طرح المشكلة على GitHub Issues.

إذا وجدت خطأ في MSAL.NET، يرجى طرح المشكلة على MSAL.NET GitHub Issues.

لتقديم توصية، انتقل إلى صفحة User Voice.

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

تعرف على المزيد حول إنشاء التطبيقات الخفية التي تستخدم النظام الأساسي للهويات في Microsoft للوصول إلى واجهات برمجة تطبيقات الويب المحمية: