البرنامج التعليمي: تعيين أدوار مخصصة باستخدام دالة وMicrosoft Graph

توضح هذه المقالة كيفية استخدام دالة للاستعلام عن Microsoft Graph وتعيين أدوار مخصصة لمستخدم بناءً على عضويته في مجموعة Active Directory.

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

• نشر تطبيق الويب الثابت.
• إنشاء تسجيل تطبيق Microsoft Entra.
• إعداد المصادقة المخصصة باستخدام معرف Microsoft Entra.
• تكوين دالة بلا خادم تستعلم عن عضوية مجموعة Active Directory للمستخدم وتعيد قائمة بالأدوار المُخصصة.

إشعار

يتطلب منك هذا البرنامج التعليمي استخدام دالة لتعيين الأدوار. إدارة الدور المستند إلى الدالة قيد المعاينة حالياً. مستوى الأذونات المطلوب لإكمال هذا البرنامج التعليمي هو "User.Read.All".

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

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

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

إنشاء مستودع GitHub

1. إنشاء مستودع استنادا إلى قالب وظيفة الأدوار. انتقل إلى الموقع التالي لإنشاء مستودع جديد.

   https://github.com/staticwebdev/roles-function/generate

2. قم بتسمية المستودع الخاص بك my-custom-roles-app.

3. حدد «Create repository from template».

نشر تطبيق الويب الثابت إلى Azure

1. في نافذة متصفح جديدة، افتح مدخل Microsoft Azure.

2. من الزاوية العلوية اليمنى، حدد Create a resource.

3. في مربع البحث، اكتب تطبيقات الويب الثابتة.

4. حدد "Static Web Apps".

5. حدد إنشاء.

6. قم بتكوين تطبيق الويب الثابت الخاص بك بالمعلومات التالية:

   الإعداد	القيمة‬	ملاحظات
   الوصف	حدد اشتراك Azure الخاص بك.
   مجموعة الموارد	إنشاء مجموعة جديدة باسم my-custom-roles-app-group.
   الاسم	my-custom-roles-app
   نوع الخطة	قياسي	يتطلب تخصيص المصادقة وتعيين الأدوار باستخدام دالة الخطة القياسية .
   المنطقة لواجهة برمجة التطبيقات	حدد أقرب منطقة إليك.

7. في قسم Deployment details :

   الإعداد	القيمة‬
   Source	حدد GitHub.
   المنظمة	حدد المؤسسة التي أنشأت المستودع فيها.
   المستودع	حدد my-custom-roles-app.
   فرع	حدد "main".

8. في قسم Build Details ، أضف تفاصيل التكوين لهذا التطبيق.

   الإعداد	القيمة‬	ملاحظات
   إنشاء إعدادات مسبقة	حدد مخصص.
   موقع التطبيق	أدخل /frontend.	يحتوي هذا المجلد على تطبيق الواجهة الأمامية.
   موقع واجهة برمجة التطبيقات	/Api	مجلد في المستودع يحتوي على وظائف واجهة برمجة التطبيقات.
   “Output location”	اترك فراغاً.	لا يحتوي هذا التطبيق على إخراج بناء.

9. حدد "Review + create".

10. حدد إنشاء بدء النشر الأول.

11. بمجرد اكتمال العملية، حدد Go to resource لفتح تطبيق الويب الثابت الجديد.

12. في قسم النظرة العامة، حدد موقع عنوان URL للتطبيق الخاص بك. انسخ هذه القيمة إلى محرر نص لاستخدامه في الخطوات القادمة لإعداد مصادقة Active Directory.

إنشاء تطبيق Microsoft Entra

1. في مدخل Microsoft Azure، ابحث عن معرف Microsoft Entra وانتقل إليه.

2. من القائمة Manage، حدد App registrations.

3. حدد New registration لفتح نافذة Register an application . أدخل القيم التالية:

   الإعداد	القيمة‬	ملاحظات
   الاسم	أدخل MyStaticWebApp.
   أنواع الحسابات المعتمدة	حدد الحسابات في هذا الدليل التنظيمي فقط.
   عنوان URI لإعادة التوجيه‬	حدد Web وأدخل عنوان URL لرد اتصال مصادقة Microsoft Entra لتطبيق الويب الثابت. استبدل <YOUR_SITE_URL> بعنوان <YOUR_SITE_URL>/.auth/login/aad/callback URL لتطبيق الويب الثابت.	عنوان URL هذا هو ما نسخته إلى محرر نص في خطوة سابقة.

   

4. حدد تسجيل.

5. بعد إنشاء تسجيل التطبيق، انسخ معرّف التطبيق (العميل) ومعرّف الدليل (المستأجر) في القسم "Essentials إلى محرر النص.

   تحتاج إلى هذه القيم لتكوين مصادقة Active Directory في تطبيق الويب الثابت.

تمكين الرموز المميزة للمعرّف

1. من إعدادات تسجيل التطبيق، حدد Authentication ضمن Manage.

2. في قسم "Implicit grant and hybrid flows"، حدد الرموز المميزة للمعرّف (المُستخدمة للتدفقات الضمنية والمختلطة).

   يتطلب وقت تشغيل Static Web Apps هذا التكوين لمصادقة المستخدمين.

3. حدد حفظ.

إنشاء سر عميل

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

2. في قسم "Client secrets"، حدد "New client secret".

3. بالنسبة لحقل الوصف، أدخل MyStaticWebApp.

4. بالنسبة للحقل Expires ، اترك القيمة الافتراضية 6 أشهر.

   إشعار

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

5. حدد إضافة.

6. انسخ قيمة سر العميل الذي أنشأته إلى محرر نص.

   تحتاج إلى هذه القيمة لتكوين مصادقة Active Directory في تطبيق الويب الثابت.

   

تكوين مصادقة Active Directory

1. في مستعرض، افتح مستودع GitHub الذي يحتوي على تطبيق الويب الثابت الذي نشرته.

   انتقل إلى ملف تكوين التطبيق في الواجهة الأمامية/staticwebapp.config.json. يحتوي هذا الملف على المقطع التالي:

   "auth": {
     "rolesSource": "/api/GetRoles",
     "identityProviders": {
       "azureActiveDirectory": {
         "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
         "registration": {
           "openIdIssuer": "https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID>",
           "clientIdSettingName": "AAD_CLIENT_ID",
           "clientSecretSettingName": "AAD_CLIENT_SECRET"
         },
         "login": {
           "loginParameters": [
             "resource=https://graph.microsoft.com"
           ]
         }
       }
     }
   },
   

   يتكون هذا التكوين من الإعدادات التالية:

   خصائص	‏‏الوصف
   rolesSource	عنوان URL حيث تحصل عملية تسجيل الدخول على قائمة الأدوار المتاحة. بالنسبة إلى نموذج التطبيق، يكون عنوان URL هو /api/GetRoles.
   userDetailsClaim	عنوان URL للمخطط المستخدم للتحقق من صحة طلب تسجيل الدخول.
   openIdIssuer	مسار تسجيل الدخول إلى Microsoft Entra، الملحق بمعرف المستأجر الخاص بك.
   clientIdSettingName	معرف عميل Microsoft Entra.
   clientSecretSettingName	القيمة السرية لعميل Microsoft Entra.
   loginParameters	للحصول على الرمز المميز للوصول لـ Microsoft Graph، يجب تكوين الحقل loginParameters باستخدام resource=https://graph.microsoft.com.

2. حدد تحرير لتحديث الملف.

3. قم بتحديث قيمة openIdIssuer من https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID> عن طريق استبدال <YOUR_AAD_TENANT_ID> بمعرف الدليل (المستأجر) لمعرف Microsoft Entra الخاص بك.

4. حدد Commit changes....

5. أدخل رسالة تثبيت، وحدد Commit changes.

   يؤدي تنفيذ هذه التغييرات إلى بدء تشغيل GitHub Actions لتحديث تطبيق الويب الثابت.

6. انتقل إلى مورد تطبيق الويب الثابت في مدخل Microsoft Azure.

7. حدد "Configuration" في شريط القائمة.

8. في القسم "Application settings"، أضِف الإعدادات التالية:

   الاسم	القيمة‬
   AAD_CLIENT_ID	معرف تطبيق Active Directory (العميل).
   AAD_CLIENT_SECRET	القيمة السرية لعميل تطبيق Active Directory.

9. حدد حفظ.

إنشاء أدوار

1. افتح تسجيل تطبيق Active Directory في مدخل Microsoft Azure.

2. ضمن إدارة، حدد أدوار التطبيق.

3. حدد Create app role وأدخل القيم التالية:

   الإعداد	القيمة
   ‏‫اسم العرض‬	أدخل المسؤول.
   أنواع الأعضاء المسموح بها	حدد Users/Groups.
   القيمة‬	أدخل المسؤول.
   ‏‏الوصف	أدخل مسؤول istrator.

4. حدد المربع هل تريد تمكين دور التطبيق هذا؟

5. حدد تطبيق.

6. الآن كرر نفس العملية لدور مسمى القارئ.

7. انسخ قيم المعرف لكل دور وقم بتعيينها جانبا في محرر نص.

التحقق من الأدوار المُخصصة

يحتوي نموذج التطبيق على دالة API (api/GetRoles/index.js) التي استعلمت عن Microsoft Graph لتحديد ما إذا كان المستخدم في مجموعة معرفة مسبقا.

استناداً إلى عضوية مجموعة المستخدم، تقوم الدالة بتعيين أدوار مُخصصة للمستخدم. تم تكوين التطبيق لتقييد مسارات معينة استناداً إلى هذه الأدوار المُخصصة.

1. في مستودع GitHub الخاص بك، انتقل إلى وظيفة GetRoles الموجودة في api/GetRoles/index.js.

   بالقرب من الجزء العلوي، هناك عنصر roleGroupMappings يقوم بتعيين أدوار مستخدم مخصصة لمجموعات Microsoft Entra.

2. حدد تحرير.

3. تحديث الكائن باستخدام معرفات المجموعة من مستأجر Microsoft Entra.

   على سبيل المثال، إذا كانت لديك مجموعات بالمعرّفات 6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 وb6059db5-9cef-4b27-9434-bb793aa31805، فيمكنك تحديث الكائن إلى:

   const roleGroupMappings = {
     'admin': '6b0b2fff-53e9-4cff-914f-dd97a13bfbd6',
     'reader': 'b6059db5-9cef-4b27-9434-bb793aa31805'
   };
   

   يتم استدعاء الدالة GetRoles كلما تمت مصادقة مستخدم بنجاح باستخدام معرف Microsoft Entra. تستخدم الدالة الرمز المميز للوصول الخاص بالمستخدم للاستعلام عن عضوية مجموعة Active Directory من Microsoft Graph. إذا كان المستخدم عضوا في أي مجموعات معرفة في roleGroupMappings العنصر، فسيتم إرجاع الأدوار المخصصة المقابلة.

   في المثال أعلاه، إذا كان المستخدم عضوا في مجموعة Active Directory ذات المعرف b6059db5-9cef-4b27-9434-bb793aa31805، يتم منحه reader الدور.

4. حدد Commit changes....

5. أضف رسالة تثبيت وحدد Commit changes.

   يؤدي إجراء هذه التغييرات إلى بدء عملية إنشاء لتحديث تطبيق الويب الثابت.

6. عند اكتمال النشر، يمكنك التحقق من التغييرات التي أجريتها من خلال الانتقال إلى عنوان URL للتطبيق.

7. سجل الدخول إلى تطبيق الويب الثابت باستخدام معرف Microsoft Entra.

8. عند تسجيل الدخول، يعرض نموذج التطبيق قائمة الأدوار التي تم تعيينها لك استنادا إلى عضوية مجموعة Active Directory الخاصة بهويتك.

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

إشعار

ترجع بعض الاستعلامات مقابل Microsoft Graph صفحات متعددة من البيانات. عند الحاجة إلى أكثر من طلب استعلام واحد، يقوم Microsoft Graph بإرجاع @odata.nextLink خاصية في الاستجابة التي تحتوي على عنوان URL إلى الصفحة التالية من النتائج. لمزيد من المعلومات، راجع ترحيل بيانات Microsoft Graph في تطبيقك

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

قم بتنظيف الموارد التي قمت بتوزيعها عن طريق حذف مجموعة الموارد.

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

2. أدخل اسم مجموعة الموارد في الحقل Filter by name.

3. حدد اسم مجموعة الموارد الذي استخدمته في هذا البرنامج التعليمي.

4. حدد Delete resource group من القائمة.

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

المصادقة والتخويل