البرنامج التعليمي: توصيل تطبيق App Service بقاعدة بيانات SQL نيابة عن المستخدم الذي سجل الدخول

يوضح لك هذا البرنامج التعليمي كيفية توصيل تطبيق Azure App Service بقاعدة بيانات Azure SQL خلفية عن طريق انتحال شخصية المستخدم الذي قام بتسجيل الدخول، والذي يطلق عليه أيضا التدفق نيابة عنه. لتكوين هذا التدفق، يمكنك تمكين المصادقة المضمنة في App Service باستخدام موفر هوية Microsoft Entra.

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

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

في هذا البرنامج التعليمي، يمكنك إضافة مصادقة Microsoft Entra إلى تطبيق ويب .NET يحتوي على واجهة خلفية لقاعدة بيانات Azure SQL. ‏‫ستتعلم كيفية:

• تمكين مصادقة Microsoft Entra لقاعدة بيانات Azure SQL.
• تعطيل خيارات مصادقة قاعدة بيانات SQL الأخرى.
• أضف معرف Microsoft Entra كموفر هوية لتطبيقك.
• تكوين إذن انتحال شخصية مستخدم قاعدة بيانات SQL.
• قم بتكوين App Service لتوفير رمز وصول قابل للاستخدام لقاعدة بيانات SQL.
• قم بالوصول إلى قاعدة بيانات Azure SQL نيابة عن مستخدم Microsoft Entra الذي قام بتسجيل الدخول.

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

إشعار

• معرف Microsoft Entra غير مدعوم ل SQL Server المحلي.
• تختلف مصادقة Microsoft Entra عن مصادقة Windows المتكاملة في خدمات مجال Active Directory (AD) المحلية (DS). يستخدم AD DS ومعرف Microsoft Entra بروتوكولات مصادقة مختلفة تماما. لمزيد من المعلومات، راجع وثائق Microsoft Entra Domain Services.

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

• الوصول إلى مستأجر Microsoft Entra المملأ بالمستخدمين والمجموعات.

• أكمل البرنامج التعليمي في البرنامج التعليمي: إنشاء تطبيق قاعدة بيانات ASP.NET Core وSQL في Azure App Service، واستخدم التطبيق المكتمل لهذا البرنامج التعليمي.

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

  • .NET Framework 4.8 والإصدارات الأحدث
  • .NET 6.0 والإصدارات الأحدث

• سجل الدخول إلى Azure Cloud Shell أو قم بإعداد بيئتك لاستخدام Azure CLI.

  • استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع بدء استخدام Azure Cloud Shell.

    

  • إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.

    • إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات تسجيل الدخول الأخرى، راجع المصادقة على Azure باستخدام Azure CLI.

    • عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات حول الملحقات، راجع استخدام الملحقات وإدارتها باستخدام Azure CLI.

    • يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

1. تكوين خادم قاعدة البيانات باستخدام مصادقة Microsoft Entra

قم بتمكين مصادقة Microsoft Entra لقاعدة بيانات Azure SQL عن طريق تعيين مستخدم Microsoft Entra كمسؤول لخادم Azure SQL. يجب أن يكون مسؤول Microsoft Entra مستخدما تم إنشاؤه أو استيراده أو مزامنته أو دعوته إلى معرف Microsoft Entra. قد لا يكون مستخدم Microsoft Entra هو نفسه مستخدم حساب Microsoft لاشتراك Azure.

لإضافة مستخدم معرف Microsoft Entra كمسؤول لخادم Azure SQL، قم بتشغيل أوامر Azure CLI التالية.

1. استخدم az ad user list مع display-nameالمعلمة ، filterأو upn للحصول على معرف الكائن لمستخدم معرف Microsoft Entra الذي تريد تعيينه مسؤولا. على سبيل المثال، يسرد الأمر التالي معلومات لمستخدم معرف Microsoft Entra مع display-name اسم العائلة للاسم الأول.

   az ad user list --display-name "Firstname Lastname"
   

   انسخ القيمة id من الإخراج لاستخدامها في الخطوة التالية.

   تلميح

   يمكنك تشغيل az ad user list مستقل لإظهار المعلومات لجميع المستخدمين في دليل Microsoft Entra.

2. أضف مستخدم معرف Microsoft Entra كمسؤول على خادم Azure SQL الخاص بك باستخدام az sql server ad-admin create المعلمة object-id . في الأمر التالي، استبدل <group-name> باسم مجموعة موارد الخادم الخاص بك، <server-name> واسم الخادم مطروحا منه .database.windows.net اللاحقة، والإخراج <entra-id>id من الأمر السابق az ad user list .

   az sql server ad-admin create --resource-group <group-name> --server-name <server-name> --display-name ADMIN --object-id <entra-id>
   

3. تقييد مصادقة خادم قاعدة البيانات بمصادقة Microsoft Entra فقط. تقوم هذه الخطوة بتعطيل مصادقة اسم مستخدم SQL وكلمة المرور.

   az sql server ad-only-auth enable --resource-group <group-name> --name <server-name>
   

• لمزيد من المعلومات حول إنشاء مستخدم Microsoft Entra، راجع إضافة مستخدمين أو حذفهم باستخدام معرف Microsoft Entra.
• لمزيد من المعلومات حول مستخدمي Microsoft Entra المسموح بهم لقاعدة بيانات SQL، راجع ميزات Microsoft Entra وقيودها في قاعدة بيانات SQL.
• لمزيد من المعلومات حول إضافة مسؤول خادم Azure SQL، راجع توفير مسؤول Microsoft Entra للخادم الخاص بك.

2. تمكين مصادقة معرف Microsoft Entra لتطبيقك

أضف معرف Microsoft Entra كموفر هوية لتطبيقك. لمزيد من المعلومات، راجع تكوين مصادقة Microsoft Entra لتطبيق App Services.

1. في صفحة مدخل Microsoft Azure لتطبيقك، حدد المصادقة ضمن الإعدادات في قائمة التنقل اليسرى.

2. في صفحة المصادقة ، حدد إضافة موفر هوية، أو حدد إضافة موفر في قسم موفر الهوية .

3. في الصفحة إضافة موفر هوية ، حدد Microsoft كموفر.

4. بالنسبة لانتهاء صلاحية سر العميل، حدد أحد خيارات القائمة المنسدلة، مثل موصى به: 180 يوما.

5. احتفظ بجميع الإعدادات الافتراضية، وحدد إضافة.

   

إشعار

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

3. تكوين انتحال شخصية مستخدم قاعدة بيانات SQL

امنح أذونات التطبيق للوصول إلى قاعدة بيانات SQL نيابة عن مستخدم Microsoft Entra الذي قام بتسجيل الدخول.

1. في صفحة المصادقة الخاصة بالتطبيق، حدد اسم التطبيق الخاص بك ضمن موفر الهوية.

   تفتح صفحة تسجيل التطبيق. تم إنشاء هذا التسجيل تلقائيا عند إضافة موفر Microsoft Entra.

2. حدد أذونات واجهة برمجة التطبيقات ضمن إدارة في قائمة التنقل اليمنى.

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

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

5. أدخل قاعدة بيانات Azure SQL في مربع البحث وحدد النتيجة.

6. ضمن نوع الأذونات التي يتطلبها تطبيقك، حدد الأذونات المفوضة، ثم حدد خانة الاختيار الموجودة بجوار user_impersonation، ثم حدد إضافة أذونات.

   

يحتوي تسجيل التطبيق في Microsoft Entra الآن على الأذونات المطلوبة للاتصال بقاعدة بيانات SQL عن طريق انتحال شخصية المستخدم الذي قام بتسجيل الدخول.

4. تكوين App Service لإرجاع رمز وصول قابل للاستخدام

لتكوين تطبيقك لتوفير رمز وصول قابل للاستخدام لقاعدة بيانات SQL، يمكنك الإضافة https://database.windows.net/user_impersonation إلى scope موفر loginParametersMicrosoft Entra الخاص بالتطبيق. يضيف الأمر التالي الخاصية loginParameters ذات النطاقات المخصصة إلى إعدادات موفر login هوية Microsoft Entra.

من بين النطاقات المطلوبة، تطلب openidApp Service بالفعل ، profileونطاقات email بشكل افتراضي. يتم تضمين offline_access النطاق حتى تتمكن من تحديث الرموز المميزة. لمزيد من المعلومات، راجع نطاقات OpenID Connect.

يشير النطاق https://database.windows.net/user_impersonation إلى قاعدة بيانات Azure SQL ويوفر رمز ويب JSON (JWT) الذي يحدد قاعدة بيانات SQL كمتلقي الرمز المميز. يستخدم jq هذا الأمر لمعالجة JSON، المثبتة بالفعل في Cloud Shell.

authSettings=$(az webapp auth show --resource-group <group-name> --name <app-name>)
authSettings=$(echo "$authSettings" | jq '.properties' | jq '.identityProviders.azureActiveDirectory.login += {"loginParameters":["scope=openid profile email offline_access https://database.windows.net/user_impersonation"]}')
az webapp auth set --resource-group <group-name> --name <app-name> --body "$authSettings"

تلميح

لتكوين النطاق المطلوب باستخدام واجهة ويب بدلا من Azure CLI، استخدم تكوين موفر Microsoft Entra لتوفير الرموز المميزة للتحديث، إضافة https://database.windows.net/user_impersonation إلى النطاقات المطلوبة.

تم تكوين تطبيقك الآن لإنشاء رمز مميز للوصول الذي تقبله قاعدة بيانات SQL.

إشعار

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

5. استخدام الرمز المميز للوصول في التعليمات البرمجية للتطبيق الخاص بك

قم بتحديث التعليمات البرمجية للتطبيق لإضافة الرمز المميز للوصول الذي توفره مصادقة App Service إلى كائن الاتصال.

إشعار

هذا الرمز لا يعمل محليا. لمزيد من المعلومات والبدائل لتصحيح الأخطاء المحلي، راجع تصحيح الأخطاء محليا عند استخدام مصادقة App Service.

1. في الكائن الخاص بك DbContext في DatabaseContext.cs أو أي ملف آخر يقوم بتكوين سياق قاعدة البيانات، قم بتغيير المنشئ الافتراضي لإضافة الرمز المميز للوصول إلى معرف Microsoft Entra إلى كائن الاتصال.

   public MyDatabaseContext (DbContextOptions<MyDatabaseContext> options, IHttpContextAccessor accessor)
       : base(options)
   {
       var conn = Database.GetDbConnection() as SqlConnection;
       conn.AccessToken = accessor.HttpContext.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];
   }
   

2. إذا كانت لديك سلسلة اتصال تسمى defaultConnection في App Service تستخدم مصادقة SQL مع اسم مستخدم وكلمة مرور، فاستخدم الأمر التالي لإزالة أسرار الاتصال. استبدل <group-name>، <app-name>، <db-server-name>، وبالقيم <db-name> الخاصة بك.

   az webapp config connection-string set --resource-group <group-name> --name <app-name> --connection-string-type SQLAzure --settings defaultConnection="server=tcp:<db-server-name>.database.windows.net;database=<db-name>;"
   

6. نشر التغييرات التي أجريتها

إذا استخدمت Visual Studio Code في المستعرض لإجراء تغييرات على التعليمات البرمجية في تفرع GitHub، فحدد التحكم في المصدر من القائمة اليسرى. أدخل رسالة التزام مثل OBO connect وحدد التزام.

يؤدي التثبيت إلى تشغيل نشر GitHub Actions إلى App Service. انتظر بضع دقائق حتى ينتهي النشر.

يمكنك أيضا نشر التغييرات التي أجريتها في Git Bash باستخدام الأوامر التالية:

git commit -am "configure managed identity"
git push azure main

إذا كانت التعليمات البرمجية الخاصة بك موجودة في Visual Studio:

1. انقر بزر الماوس الأيمن فوق مشروعك في مستكشف الحلول وحدد نشر.

   

2. في صفحة نشر ، حدد نشر.

عندما تعرض صفحة التطبيق الجديدة تطبيقك، يتصل التطبيق بقاعدة بيانات Azure SQL نيابة عن مستخدم Microsoft Entra الذي قام بتسجيل الدخول. يجب أن تكون قادرا على استخدام تطبيقك وتحريره كالمعتاد.

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

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

az group delete --name <group-name>

قد يستغرق تشغيل هذا الأمر بعض الوقت.

الأسئلة الشائعة

• لماذا أحصل على الخطأ "فشل تسجيل الدخول للمستخدم '<الرمز المميز'>"؟
• كيف أعمل إضافة مستخدمين أو مجموعات Microsoft Entra أخرى في قاعدة بيانات Azure SQL؟
• كيف أعمل تصحيح الأخطاء محليا عند استخدام مصادقة App Service؟
• ماذا يحدث عند انتهاء صلاحية رموز الوصول المميزة؟

لماذا أحصل على الخطأ "فشل تسجيل الدخول للمستخدم '<الرمز المميز'>"؟

الأسباب الأكثر شيوعا للخطأ Login failed for user '<token-identified principal>' هي:

• مصادقة Microsoft Entra لم يتم تكوينها لقاعدة بيانات Azure SQL. راجع تكوين خادم قاعدة البيانات باستخدام مصادقة Microsoft Entra.
• لا يوجد رمز مميز صالح في X-MS-TOKEN-AAD-ACCESS-TOKEN رأس الطلب. لا تعمل هذه التعليمات البرمجية في البيئات المحلية. لمزيد من المعلومات والبدائل، راجع تصحيح الأخطاء محليا عند استخدام مصادقة App Service.
• لا يمتلك المستخدم إذنا للاتصال بقاعدة البيانات. لإضافة مستخدمين وأذونات، راجع إضافة مستخدمي أو مجموعات Microsoft Entra الأخرى في قاعدة بيانات Azure SQL.

كيف أعمل إضافة مستخدمين أو مجموعات Microsoft Entra أخرى في قاعدة بيانات Azure SQL؟

لإضافة المزيد من المستخدمين أو المجموعات، اتصل بخادم قاعدة البيانات باستخدام sqlcmd أو SQL Server Management Studio (SSMS)، وقم بإنشاء مستخدمي قاعدة بيانات مضمنين تم تعيينهم إلى هويات Microsoft Entra.

يضيف المثال Transact-SQL التالي هوية Microsoft Entra إلى SQL Server ويمنح الهوية بعض أدوار قاعدة البيانات:

CREATE USER [<user-or-group-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<user-or-group-name>];
ALTER ROLE db_datawriter ADD MEMBER [<user-or-group-name>];
ALTER ROLE db_ddladmin ADD MEMBER [<user-or-group-name>];
GO

كيف أعمل تصحيح الأخطاء محليا عند استخدام مصادقة App Service؟

نظرا لأن مصادقة App Service هي ميزة Azure، فإن التعليمات البرمجية في هذا البرنامج التعليمي لا تعمل في بيئتك المحلية. على عكس التطبيق الذي يعمل في Azure، لا تستفيد التعليمات البرمجية المحلية من البرامج الوسيطة لمصادقة App Service. يمكنك استخدام البدائل التالية لتصحيح الأخطاء المحلية:

• اتصل بقاعدة بيانات SQL من بيئتك المحلية باستخدام Active Directory Interactive المصادقة. لا يقوم تدفق المصادقة هذا بتسجيل دخول المستخدم نفسه، ولكنه يتصل بقاعدة البيانات الخلفية مع المستخدم الذي قام بتسجيل الدخول حتى تتمكن من اختبار تخويل قاعدة البيانات محليا.
• انسخ رمز الوصول المميز يدويا إلى التعليمات البرمجية بدلا من X-MS-TOKEN-AAD-ACCESS-TOKEN رأس الطلب.
• إذا قمت بالنشر من Visual Studio، فاستخدم تصحيح الأخطاء عن بعد لتطبيق App Service.

ماذا يحدث عند انتهاء صلاحية رموز الوصول المميزة؟

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

محتوى ذو صلة

• البرنامج التعليمي: الاتصال بقواعد بيانات Azure من App Service دون بيانات سرية باستخدام الهوية المُدارة
• البرنامج التعليمي: الوصول إلى Microsoft Graph من تطبيق .NET آمن كتطبيق
• البرنامج التعليمي: عزل الاتصال الخلفي مع تكامل الشبكة الظاهرية
• تعيين اسم DNS حالي مخصص إلى Azure App Service