إتقان تسجيلات تطبيقات Entra ID متعددة المستأجرين لـ SPFx

By Mirko Peters · 2026-08-11

أهلاً بعودتكم إلى البودكاست! إذا سبق لك أن حاولت نقل حل SPFx بُني بعناية في مستأجر التطوير الخاص بك إلى بيئة عميل، فأنت تعرف الشعور المحبط حين ينهار كل شيء. صمت تام. أجزاء ويب فارغة. حلقات لا تنتهي من تسجيل الدخول. المصادقة عبر المستأجرات هي الاختبار الأصعب لمطوري Microsoft 365، ولإتقانها يلزم فهم دقيق لتسجيلات تطبيقات Entra ID والنطاقات الديناميكية وأمان أقل الصلاحيات.

Automatically translated with AI from the original post. Read the English original

Titelbild: Mastering Multi-Tenant Entra ID App Registrations for SPFx

أهلاً بعودتكم إلى البودكاست! إذا سبق لك أن حاولت نقل حل SPFx بُني بعناية في مستأجر التطوير الخاص بك إلى بيئة عميل، فأنت تعرف الشعور المحبط حين ينهار كل شيء تماماً. صمت تام. أجزاء ويب فارغة. حلقات لا تنتهي من تسجيل الدخول. المصادقة عبر المستأجرات هي الاختبار الأصعب لمطوري Microsoft 365، والتعامل معها بشكل صحيح يتطلب إتقان تفاصيل تسجيلات تطبيقات Entra ID والنطاقات الديناميكية وأمان أقل الصلاحيات.

في هذا الدليل الشامل، نتوسع في كل ما ناقشناه في آخر حلقة. وللتعمق أكثر في النقاش الصوتي، استمعوا إلى تحليلنا المفصل بعنوان Fix Multi-Tenant SPFx Authentication.

المقدمة: لماذا يُعد SPFx متعدد المستأجرين مستوى صعباً

يُوصف نقل تطبيق SPFx عبر حدود الهوية غالباً بأنه "مستوى صعب"، ولهذا سبب وجيه. عند البناء داخل مستأجر واحد، تكون Entra ID وبنى مواقع SharePoint وأذونات واجهات البرمجة ضمنية إلى حد كبير، أو يمكن تجاوزها بسهولة عبر صلاحيات مسؤول عام. لكن لحظة الدخول إلى نموذج متعدد المستأجرين، سواء كنت مزود برمجيات مستقل (ISV) تطرح جزء ويب للبيع، أو فريق تقنية معلومات داخلي يدير عدة مستأجرات تابعة، تختفي تلك الاختصارات.

أنت الآن تتعامل مع حدود أدلة صارمة، وأطر موافقة تتطلب اعتماداً إدارياً صريحاً، وطبولوجيات مواقع فريدة. إذا كان تسجيل تطبيقك مقيّداً بمستأجر واحد، أو إذا كان الكود يعتمد على معاملات بيئة مرمّزة مسبقاً، فسيفشل النشر في الإنتاج حتماً.

لمن هذا الدليل؟

قبل الخوض في الجوانب التقنية، دعونا نحدد من يحتاج إلى إتقان نمط المعمارية هذا:

مطورو SPFx وconsultants في Microsoft 365 الذين يطرحون حلولهم لعدة مستأجرات ويريدون تجنب إعادة الضبط اليدوي في كل عملية نشر لعميل.
مسؤولو تقنية المعلومات ومزودو الخدمات المُدارة (MSPs) الذين يدعمون بيئات SharePoint Online للعملاء ويحتاجون إلى الحفاظ على وضع أمني صارم مع تمكين حلول المطورين الحديثة.
الشركاء ومزودو البرمجيات المستقلون الذين يطرحون أجزاء ويب وامتدادات SPFx ويحتاجون إلى مسار قابل للتكرار والتوسع للوصول إلى السوق عبر مئات المستأجرات المختلفة للعملاء.

النقاط الرئيسية

للتعامل بنجاح مع عمليات النشر متعددة المستأجرين، اجعلوا هذه المبادئ الأساسية في صدارة معماريتكم:

المصادقة ليست قالباً جاهزاً: استخدموا تطبيق Entra ID متعدد المستأجرين، واشترطوا موافقة مسؤول لكل مستأجر؛ وتحققوا من هذه الحالات الأمنية أثناء التشغيل.
لا تُدرجوا تفاصيل المستأجر في الكود أبداً: حمّلوا عناوين URL والمعرّفات والنطاقات ديناميكياً من مصدر إعدادات يدرك المستأجر؛ واحفظوا أي أسرار خلفية لازمة بأمان في Azure Key Vault.
نتائج Graph الفارغة لا تعني أن الكود معطّل: عندما يُرجع Microsoft Graph مصفوفات فارغة، فالسبب في الغالب غياب الموافقة أو عدم تطابق بيانات الدليل أو المرشحات، وليس خطأ في بناء الجملة داخل قاعدة الكود.
حزمة واحدة، ومستأجرات كثيرة: صمموا حلول SPFx بحيث تكون مستقلة تماماً عن المستأجر، مع عمليات نشر محددة النطاق لكل مستأجر، لتجنب بناء نسخ مخصصة لكل عميل.
اكتشفوا الأعطال مبكراً: اجمعوا القياسات عن بُعد وفحوص الصحة في مكان واحد باستخدام Application Insights أو Azure Monitor مُهيأة لكل مستأجر.

أبرز المحطات

خلال استكشافنا التقني، توقفنا عند عدة محطات حرجة يجب معالجتها في دورة حياة التطوير لديكم:

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

قائمة التحقق السريعة (نسخ/لصق)

تسجيل تطبيق Entra ID
- اضبط أنواع الحسابات المدعومة: متعدد المستأجرين.
- حدّد نطاقات Graph المفوّضة الدقيقة اللازمة، وفق مبدأ أقل الامتيازات.
- اضبط عناوين URI لإعادة التوجيه الصالحة بحيث تغطي SharePoint Online وبيئات التطوير المحلية لديك.
تقوية مشروع SPFx
- استخدم MSGraphClient أو AadHttpClient في جميع استدعاءات واجهات برمجة التطبيقات المفوّضة.
- اقرأ الإعدادات الخاصة بكل مستأجر (مثل نقاط النهاية ومعرّفات مواقع الاستهداف) من قائمة إعدادات مخصّصة في SharePoint أو من واجهة برمجة تطبيقات آمنة، وتأكد من عدم وجود أي أسرار في كود الواجهة الأمامية.
- نفّذ فحوصات الأذونات أثناء التشغيل، بحيث تعرض بسلاسة لافتة "Admin consent required" تتضمن رابطًا عميقًا مباشرًا عند غياب الأذونات.
تدفق الموافقة
- وفّر صفحة مخصّصة لتهيئة المستأجر تعرض النطاقات المطلوبة، وعنوان URL الدقيق لموافقة المسؤول، وخطوات التحقق.
- ادعم نماذج الموافقة لكل فئة مستهدفة، مع التمييز بين الطرح على مستوى المؤسسة بأكملها والتجربة على مجموعة مستهدفة.
التغليف والنشر
- غلّف الحل مرة واحدة في ملف .sppkg قياسي، وفعّل النشر المحصور في نطاق المستأجر حيثما يكون مناسبًا.
- انشر عبر كتالوج تطبيقات مركزي (App Catalog) مع توثيق مفصّل لخطوات الإضافة على مستوى الموقع.
- أتمِت دورة الإصدار باستخدام خط أنابيب CI/CD متين (بناء، وحزم، وتغليف، ورفع، ونشر).
المراقبة والدعم
- أصدر بيانات قياس تفصيلية، تشمل معرّف المستأجر، ومعرّف الارتباط (correlation ID)، والميزات المحددة، ورموز الأخطاء.
- اربط لوحات Application Insights أو Azure Monitor مع تنبيهات قابلة للتنفيذ.
- وثّق إجراء استرجاع واضحًا باستخدام إصدارات الحزم السابقة، إلى جانب خريطة إصدارات تفصيلية لكل مستأجر.

الأخطاء الشائعة (وطرق المعالجة)

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

العَرَض: حلقات تسجيل دخول متكررة، أو السيناريو المزعج "يعمل عندي ولا يعمل عندهم".
السبب: ما زال تسجيل تطبيق Entra ID مهيّأً كمستأجر واحد، أو أن عناوين الرد (reply URLs) لا تطابق البيئة المستهدفة.
الحل: حوّل تسجيل التطبيق إلى متعدد المستأجرين، وصحّح عناوين URI لإعادة التوجيه، ثم أطلق طلب موافقة جديدًا.
العَرَض: تُرجع Microsoft Graph مجموعات بيانات فارغة تمامًا.
السبب: غياب موافقة مسؤول المستأجر، أو مرشحات الدليل المقيّدة بشدة.
الحل: شغّل تدفق موافقة المسؤول المناسب، واختبر استعلاماتك مباشرة في Graph Explorer باستخدام مستخدم حقيقي من مستأجر العميل، وخفّف الافتراضات أو المرشحات الصارمة في الكود.
العَرَض: لا يستطيع المستخدمون إضافة ويب بارت إلى صفحاتهم.
السبب: لم تُنشر الحزمة بشكل صحيح في كتالوج تطبيقات المستأجر، أو أن نهج التطبيقات التنظيمية تحجبها.
الحل: تحقّق من حالة النشر في App Catalog، وراجع إعدادات التطبيقات والنهج على مستوى المستأجر.
العَرَض: الحاجة إلى إعادة بناء الحزمة مع كل تغيير بسيط في الإعدادات عبر العملاء.
السبب: معرّفات أو عناوين URL أو أسرار مدمجة مباشرة في الحزمة.
الحل: انقل الإعدادات إلى خارج الكود، واعتمد على قوائم إعدادات SharePoint أو Azure Key Vault، واقرأ هذه القيم ديناميكيًا أثناء التشغيل.

أساسيات الحوكمة والأمن

لا يمكن أن يكون الأمن فكرة لاحقة عند نشر الكود في أدلة العملاء الخارجية. طبّق أساسيات الحوكمة التالية للحفاظ على الثقة:

فرض نطاقات بأقل الامتيازات، وأجرِ مراجعات دورية للنطاقات لإزالة الأذونات غير المستخدمة.
خزّن أسرار التطبيقات الخلفية بأمان في Azure Key Vault، وضع جدولًا منتظمًا لتدويرها.
استفد من نهج الأذونات الخاصة بتطبيقات Teams وSharePoint لتقييد الجماهير المستهدفة بإحكام ومنع الاستخدام غير المصرح به.
احتفظ بسجل موافقات شامل يتتبع من وافق، ومتى مُنحت الموافقة، وما النطاقات التي أُقرّت.
واءم علامة ويب بارت التجارية ديناميكيًا عبر واجهات برمجة سمات Microsoft 365، بدلًا من تضمين أصول تنسيق خاصة بالمستأجر داخل الكود.

خطة التحقق (قبل التسليم للعميل)

لا تنشر أبدًا دون تحقق. نفّذ خطة التحقق هذه قبل عرض الحل على العميل:

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

الأسئلة المتداولة

هل أحتاج إلى أذونات التطبيق لحلول SPFx؟
عادةً لا. تعمل حلول SPFx ضمن سياق المستخدم المفوَّض. تتطلب أذونات التطبيق موافقات إدارية إضافية ونماذج معمارية متخصصة، لذا استخدمها فقط عندما لا يتوفر أي بديل عملي آخر.

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

كيف أحافظ على قاعدة كود واحدة لعملاء متعددين؟
اجعل حلّك مستقلاً تماماً عن المستأجر، واستخرج جميع الإعدادات الخاصة بالبيئات إلى خارج الكود، وأتمتْ عمليات التغليف والنشر. واستخدم أعلام الميزات لإدارة الخيارات الخاصة بكل عميل بأمان.

كيف أشخّص مشكلة "البيانات فارغة" بسرعة أكبر؟
سجّل استجابات Graph الخام إلى جانب فحوصات التحقق من النطاقات. عند حدوث فشل، اعرض إشعاراً مضمّناً يتضمن العبارة "الموافقة مفقودة أو النطاق غير كافٍ" مع رابط عميق مباشر لمعالجة المشكلة فوراً.

الخلاصة

إتقان تسجيلات تطبيقات Entra ID متعددة المستأجرين لحلول SharePoint Framework هو ما يفصل بين السكربتات الهاوية ومنتجات البرمجيات المؤسسية. فبتحويل تفكيرك نحو التغليف المستقل عن المستأجر، وتحميل الإعدادات بشكل ديناميكي، والتحقق القوي من الموافقة أثناء التشغيل، يمكنك القضاء على أعطال النشر الصامتة وتقديم تجارب سلسة لكل عميل.

للاستماع إلى المزيد عن القصص الواقعية والقرارات المعمارية التي تقف وراء هذه الحلول، تأكد من متابعة حلقة البودكاست ذات الصلة: Fix Multi-Tenant SPFx Authentication. شكرًا لقراءتك، وبالتوفيق في البرمجة!