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

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

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

في هذا البرنامج التعليمي، يمكنك إضافة مصادقة Microsoft Entra إلى نموذج تطبيق الويب الذي قمت بنشره في أحد البرامج التعليمية التالية:

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

عند الانتهاء، سيقوم نموذج التطبيق الخاص بك بمصادقة المستخدمين المتصلين بقاعدة بيانات SQL بشكل آمن نيابة عن المستخدم الذي قام بتسجيل الدخول.

إشعار

الخطوات المغطاة بهذا البرنامج التعليمي تدعم الإصدارات التالية:

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

سوف تتعلم ما يلي:

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

إشعار

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

إذا لم يكن لديك حساب Azure، فأنشئ حساباً مجانياً قبل أن تبدأ.

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

تستمر هذه المقالة من حيث توقفت في أي من الدروس التالية:

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

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

تحضير البيئة الخاصة بك لـAzure CLI.

Azure يستضيف Azure Cloud Shell، بيئة تفاعلية يمكن استخدامها من خلال المستعرض. يمكنك استخدام Bash أو PowerShell مع Cloud Shell للعمل مع خدمات Azure. يمكنك استخدام أوامر Cloud Shell المثبتة مسبقًا لتشغيل التعليمات البرمجية في هذه المقالة دون الحاجة إلى تثبيت أي شيء على البيئة المحلية.

لبدء Azure Cloud Shell:

خيار	مثال/ رابط
انقر فوق ⁧⁩جربه⁧⁩ في الزاوية العلوية اليسرى من التعليمة البرمجية أو كتلة الأمر. تحديد ⁧⁩جربه⁧⁩ لا يقوم بنسخ التعليمة البرمجية أو الأمر تلقائيًا إلى Cloud Shell.
انتقل إلى ⁧⁩⁧ https://shell.azure.com⁩⁧⁩، أو حدد زر ⁩تشغيل Cloud Shell لفتح Cloud Shell في المتصفح لديك.
حدد زر Cloud Shell على شريط القوائم في أعلى اليمين في مدخل Microsoft Azure.

لاستخدام Azure Cloud Shell:

1. ابدأ تشغيل Cloud Shell.

2. حدد الزر نسخ على كتلة التعليمات البرمجية (أو كتلة الأوامر) لنسخ التعليمات البرمجية أو الأمر.

3. ألصق التعليمة البرمجية أو الأمر في جلسة Cloud Shell بتحديد Ctrl+Shift+Vعلى Windows وLunix، أو بتحديد Cmd+Shift+Vعلى macOS.

4. حدد Enter لتشغيل التعليمات البرمجية أو الأمر.

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

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

1. إذا لم يكن لدى مستأجر Microsoft Entra مستخدم حتى الآن، فبادر بإنشاء مستخدم باتباع الخطوات الواردة في إضافة مستخدمين أو حذفهم باستخدام معرف Microsoft Entra.

2. ابحث عن معرف الكائن لمستخدم Microsoft Entra باستخدام az ad user list واستبدل <user-principal-name>. يتم حفظ النتيجة لمتغير.

   azureaduser=$(az ad user list --filter "userPrincipalName eq '<user-principal-name>'" --query [].id --output tsv)
   

   تلميح

   لمشاهدة قائمة بجميع أسماء المستخدمين الأساسية في معرف Microsoft Entra، قم بتشغيل az ad user list --query [].userPrincipalName.

3. أضف مستخدم Microsoft Entra هذا كمسؤول Active Directory باستخدام az sql server ad-admin create الأمر في Cloud Shell. في الأمر التالي، استبدل <server-name> باسم الخادم (دون اللاحقة .database.windows.net ).

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

4. تقييد مصادقة خادم قاعدة البيانات إلى مصادقة Active Directory. تعطل هذه الخطوة مصادقة SQL بشكل فعال.

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

لمزيد من المعلومات حول إضافة مسؤول Active Directory، راجع توفير مسؤول Microsoft Entra (قاعدة بيانات SQL).

2. تمكين مصادقة المستخدم لتطبيقك

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

1. في قائمة Azure portal، حدد مجموعات الموارد ، أو ابحث عنها وحدد مجموعات الموارد من أي صفحة.

2. في مجموعات الموارد، ابحث عن مجموعة الموارد وحددها، ثم حدد تطبيقك.

3. في القائمة اليسرى لتطبيقك، حدد Authentication، ثم حدد Add identity provider.

4. في صفحة إضافة موفر هوية، حدد Microsoft كموفر الهوية لتسجيل الدخول إلى هويات Microsoft وMicrosoft Entra.

5. اقبل الإعدادات الافتراضية وحدد إضافة.

   

تلميح

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

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

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

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

2. حدد إضافة إذن، ثم حدد واجهات برمجة التطبيقات التي تستخدمها مؤسستي.

3. اكتب Azure SQL Database في مربع البحث وحدد النتيجة.

4. في صفحة طلب أذونات واجهة برمجة التطبيقات لقاعدة بيانات Azure SQL، حدد الأذونات المفوضة user_impersonation، ثم حدد إضافة أذونات.

   

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

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

في Cloud Shell، قم بتشغيل الأوامر التالية على التطبيق لإضافة المعلمة scope إلى إعداد identityProviders.azureActiveDirectory.login.loginParametersالمصادقة . يستخدم [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"

تضيف الأوامر بشكل فعال خاصية loginParameters مع نطاقات مخصصة إضافية. وفيما يلي شرح للنطاق المطلوب:

• openid،profile، وemail يتم طلبها من قبل App Service بشكل افتراضي بالفعل. للحصول على معلومات، راجع OpenID Connect Scopes.
• https://database.windows.net/user_impersonation يشير إلى قاعدة بيانات Azure SQL. إنه النطاق الذي يمنحك JWT الذي يتضمن قاعدة بيانات SQL كجمهور رمز مميز.
• offline_access مضمن هنا للراحة (في حالة رغبتك في تحديث الرموز).

تلميح

لتكوين النطاقات المطلوبة باستخدام واجهة ويب بدلاً من ذلك، راجع خطوات Microsoft في تحديث الرموز المميزة.

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

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

تعتمد الخطوات التي تتبعها لمشروعك على ما إذا كنت تستخدم Entity Framework (افتراضي لـ ASP.NET) أو Entity Framework Core (افتراضي لـ ASP.NET Core).

إطار عمل الكيان

1. في Visual Studio، افتح وحدة التحكم مدير الحِزَم وتحديث Entity Framework:

   Update-Package EntityFramework
   

2. في عنصر DbContext الخاص بك (في Models/MyDbContext.cs)، أضف التعليمة البرمجية التالية إلى الدالة الإنشائية الافتراضي.

   var conn = (System.Data.SqlClient.SqlConnection)Database.Connection;
   conn.AccessToken = System.Web.HttpContext.Current.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];
   

Entity Framework Core

في العنصر ( DbContext في Models/MyDbContext.cs)، قم بتغيير الدالة الإنشائية الافتراضية إلى ما يلي.

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"];
}

إشعار

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

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

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

ASP.NET

1. إذا كنت من البرنامج التعليمي: إنشاء تطبيق ASP.NET في Azure باستخدام قاعدة بيانات SQL، يمكنك تعيين سلسلة الاتصال في App Service باستخدام مصادقة SQL، مع اسم مستخدم وكلمة مرور. استخدم الأمر التالي لإزالة أسرار الاتصال، ولكن استبدل group-name<>

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

2. نشر التغييرات في Visual Studio. في مستكشف الحلول، انقر بزر الماوس الأيمن فوق مشروع DotNetAppSqlDb وحدد Publish.

   

3. في صفحة النشر، حدد Publish.

ASP.NET Core

1. إذا كنت من البرنامج التعليمي: إنشاء تطبيق ASP.NET Core وSQL Database في Azure App Service، فلديك سلسلة الاتصال يسمى defaultConnection في App Service باستخدام مصادقة SQL، مع اسم مستخدم وكلمة مرور. استخدم الأمر التالي لإزالة أسرار الاتصال، ولكن استبدل group-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>;"
   

2. كنت لإجراء تغييرات التعليمات البرمجية في نسخة GitHub الخاصة بك، مع Visual Studio Code في المتصفح. من القائمة اليسرى، حدد التحكم بالمصادر.

3. اكتب رسالة تثبيت مثل OBO connect وحدد Commit.

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

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

يجب أن تكون قادرًا الآن على تحرير قائمة المهام كما كان من قبل.

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

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

az group delete --name <group-name>

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

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

• لماذا أحصل على خطأ Login failed for user '<token-identified principal>'. ؟
• كيف أعمل إضافة مستخدمين أو مجموعات Microsoft Entra أخرى في قاعدة بيانات Azure SQL؟
• كيف أعمل تصحيح الأخطاء محليا عند استخدام مصادقة App Service؟
• ماذا يحدث عند انتهاء صلاحية رموز الوصول المميزة؟

لماذا أحصل على خطأ Login failed for user '<token-identified principal>'. ؟

الأسباب الأكثر شيوعا لهذا الخطأ هي:

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

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

1. اتصل بخادم قاعدة البيانات، مثل sqlcmd أو SSMS.

2. إنشاء مستخدمين مضمنين تم تعيينهم إلى هويات Microsoft Entra في وثائق قاعدة بيانات SQL.

   يضيف مثال 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 SQL
• تعطيل خيارات المصادقة الأخرى في قاعدة بيانات Azure SQL
• تمكين مصادقة App Service
• استخدام معرف Microsoft Entra كموفر هوية
• الوصول إلى قاعدة بيانات Azure SQL نيابة عن مستخدم Microsoft Entra الذي سجل الدخول

تعيين اسم DNS حالي مخصص إلى Azure App Service

البرنامج التعليمي: الوصول إلى Microsoft Graph من تطبيق .NET آمن كتطبيق

البرنامج التعليمي: عزل الاتصال الخلفي مع تكامل الشبكة الظاهرية