البرنامج التعليمي: استخدام مراجع Key Vault في تطبيق ASP.NET Core

في هذا البرنامج التعليمي، ستتعلم كيفية استخدام خدمة تكوين تطبيق Azure مع Azure Key Vault. تكوين التطبيق وKey Vault هما خدمات تكميلية تستخدم جنبًا إلى جنب في معظم عمليات النشر للتطبيقات.

يساعدك تكوين التطبيق على استخدام الخدمات معًا من خلال إنشاء مفاتيح تشير إلى قيم المراجع المخزنة في Key Vault. عندما ينشئ تكوين التطبيق مثل هذه المفاتيح، فإنه يخزن URI لقيم Key Vault بدلاً من القيم نفسها.

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

تطبيقك هو المسؤول عن المصادقة بشكل صحيح على كل من تكوين التطبيق وKey Vault. لا تتصل الخدمتان مباشرة.

يوضح لك هذا البرنامج التعليمي كيفية تنفيذ مراجع Key Vault في الكود الخاص بك. وهو يبني على تطبيق الويب الذي تم تقديمه في البدايات سريعة. قبل المتابعة، عليك إنهاء إنشاء تطبيق ASP.NET Core باستخدام تكوين التطبيق أولاً.

يمكنك استخدام أي محرر تعليمات برمجية للقيام بالخطوات الواردة في هذا البرنامج التعليمي. على سبيل المثال، Visual Studio Code هو محرر كود متعدد الأنظمة متاح لأنظمة تشغيل Windows وmacOS وLinux.

في هذا البرنامج التعليمي، تتعلم كيفية:

• إنشاء مفتاح تكوين التطبيق الذي يشير إلى قيمة مخزنة في Key Vault.
• يمكنك الوصول إلى قيمة هذا المفتاح من تطبيق ويب ASP.NET Core.

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

قبل بدء هذا البرنامج التعليمي، قم بتثبيت .NET SDK 6.0 أو أحدث.

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

أنشئ مخزنًا

1. حدّد خيار إنشاء مورد في الزاوية العلوية اليسرى من مدخل Microsoft Azure:

   

2. في مربع البحث، اكتب Key Vault وحدد Key Vault من القائمة المنسدلة.

3. من قائمة النتائج، حدد المخازن الرئيسية على اليسار.

4. في المخازن الرئيسية، حدد إضافة.

5. على اليمين في إنشاء مخزن رئيسي، قم بتوفير المعلومات التالية:

   • حدد اشتراك لاختيار اشتراك.
   • في Resource Group، أدخل اسم مجموعة موارد موجود أو حدد Create new وأدخل اسم مجموعة موارد.
   • في اسم المخزن الرئيسي، مطلوب اسم فريد.
   • في قائمة ⁧⁩المنطقة⁧⁩ المنسدلة، اختر موقعًا.

6. اترك الخيارات الأخرى لإنشاء مخزن رئيسي بقيمها الافتراضية.

7. انقر فوق Review + Create.

8. سيتحقق النظام من صحة البيانات التي أدخلتها وعرضها. انقر فوق Create.

في هذه المرحلة، حساب Azure الخاص بك هو الوحيد المخول بالوصول إلى هذا المخزن الجديد.

إضافة سر إلى Key Vault

لإضافة سر إلى المخزن، تحتاج إلى اتخاذ بضعة خطوات إضافية فقط. في هذه الحالة، أضف رسالة يمكنك استخدامها لاختبار استرداد Key Vault. تسمى الرسالة رسالة، ويمكنك تخزين القيمة "مرحبًا من Key Vault" فيها.

1. من صفحات خصائص Key Vault، حدد أسرار.
2. حدد إنشاء/استيراد.
3. في جزء Create a secret ، أدخل القيم التالية:
   • خيارات التحميل: أَدخِل يدويًا.
   • الاسم: أَدخِل رسالة.
   • القيمة: أَدخِل مرحبًا من Key Vault.
4. اترك الخصائص الأخرى لإنشاء سر بقيمها الافتراضية.
5. حدد إنشاء.

أضف مرجع Key Vault إلى تكوين التطبيق

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

2. حدد Configuration Explorer.

3. حدد + Create>Key vault reference، ثم حدد القيم التالية:

   • المفتاح: حدد TestApp:الإعدادات:KeyVaultMessage.
   • Label: اترك هذه القيمة فارغة.
   • الاشتراك ومجموعة الموارد وKey vault: أدخل القيم المطابقة لتلك الموجودة في خزنة المفاتيح التي أنشأتها في القسم السابق.
   • سر: حدد الرسالة المسماة السرية التي قمت بإنشائها في القسم السابق.

حَدِّث التعليمات البرمجية الخاصة بك لاستخدام مرجع Key Vault

1. أضف مرجعًا إلى حزم NuGet المطلوبة عن طريق تشغيل الأمر التالي:

   dotnet add package Azure.Identity
   

2. افتح Program.cs، وأضف مراجع إلى الحزم المطلوبة التالية:

   using Azure.Identity;
   

3. استخدم App Configuration عن طريق استدعاء AddAzureAppConfiguration الأسلوب . قم بتضمين ConfigureKeyVaultالخيار، وقم بتمرير بيانات الاعتماد الصحيحة إلى Key Vault الخاص بك باستخدامSetCredential الطريقة.

   var builder = WebApplication.CreateBuilder(args);
   
   // Retrieve the connection string
   string connectionString = builder.Configuration.GetConnectionString("AppConfig");
   
   // Load configuration from Azure App Configuration
   builder.Configuration.AddAzureAppConfiguration(options =>
   {
       options.Connect(connectionString);
   
       options.ConfigureKeyVault(keyVaultOptions =>
       {
           keyVaultOptions.SetCredential(new DefaultAzureCredential());
       });
   });
   

   تلميح

   إذا كان لديك العديد من Key Vaults، فسيتم استخدام بيانات الاعتماد نفسها لجميعها. إذا كانت Key Vaults تتطلب بيانات اعتماد مختلفة، يمكنك تعيينها باستخدام Register أو SetSecretResolver أساليب من AzureAppConfigurationKeyVaultOptions الفئة.

4. عند تهيئة الاتصال بتكوين التطبيق، يمكنك إعداد الاتصال ب Key Vault عن طريق استدعاء ConfigureKeyVault الأسلوب . بعد التهيئة، يمكنك الوصول إلى قيم مراجع Key Vault بالطريقة نفسها التي تصل بها إلى قيم مفاتيح تكوين التطبيق العادية.

   لمشاهدة هذه العملية قيد التنفيذ، افتح Index.cshtml في مجلد Views>Home. استبدال محتوياته مع الرمز التالي:

   @page
   @using Microsoft.Extensions.Configuration
   @inject IConfiguration Configuration
   
   <style>
       body {
           background-color: @Configuration["TestApp:Settings:BackgroundColor"]
       }
       h1 {
           color: @Configuration["TestApp:Settings:FontColor"];
           font-size: @Configuration["TestApp:Settings:FontSize"]px;
       }
   </style>
   
   <h1>@Configuration["TestApp:Settings:Message"]
       and @Configuration["TestApp:Settings:KeyVaultMessage"]</h1>
   

   يمكنك الوصول إلى قيمة مرجع Key Vault TestApp:الإعدادات:KeyVaultMessage بنفس الطريقة التي يتم بها الوصول إلى قيمة تكوين TestApp:الإعدادات:Message.

امنح التطبيق الخاص بك الوصول إلىKey Vault

لن يصل تكوين تطبيق Azure إلى Key Vault لديك. ستتم قراءة تطبيقك من Key Vault مباشرة، لذلك تحتاج إلى منح تطبيقك حق الوصول إلى الأسرار في مخزن المفاتيح الخاص بك. بهذه الطريقة، يبقى السر دائمًا في تطبيقك. يمكن منح الوصول باستخدام نهج الوصول إلى Key Vault أو التحكم في الوصول المستند إلى الدور في Azure.

يمكنك استخدام DefaultAzureCredential في التعليمات البرمجية أعلاه. إنها بيانات اعتماد رمزية مجمعة تحاول تلقائيا عدد من أنواع بيانات الاعتماد، مثل EnvironmentCredentialو ManagedIdentityCredentialSharedTokenCacheCredentialو وVisualStudioCredential. لمزيد من المعلومات، راجع فئة DefaultAzureCredential. يمكنك استبدال DefaultAzureCredential بأي نوع بيانات اعتماد بشكل صريح. ومع ذلك، يمكنك استخدام DefaultAzureCredential من الحصول على نفس التعليمات البرمجية التي تعمل في كل من البيئات المحلية وبيئات Azure. على سبيل المثال، تمنح حق الوصول إلى بيانات الاعتماد الخاصة بك إلى Key Vault لديك. DefaultAzureCredential الرجوع تلقائيا إلى SharedTokenCacheCredential أو VisualStudioCredential عند استخدام Visual Studio للتطوير المحلي.

بدلا من ذلك، يمكنك تعيين متغيرات البيئة AZURE_TENANT_ID AZURE_CLIENT_ID AZURE_CLIENT_SECRET، DefaultAzureCredential وستستخدم سر العميل الذي لديك عبر EnvironmentCredential للمصادقة مع مخزن المفاتيح الخاص بك. بعد نشر تطبيقك في خدمة Azure مع تمكين الهوية المُدارة، مثل Azure App Service، أو Azure Kubernetes Service، أو Azure Container Instance، فإنك تمنح الهوية المُدارة لإذن خدمة Azure للوصول إلى Key Vault لديك. DefaultAzureCredential يستخدم ManagedIdentityCredential تلقائيا عند تشغيل تطبيقك في Azure. يمكنك استخدام الهوية المُدارة نفسها للمصادقة مع App Configuration وKey Vault على حدٍ سواء. لمزيد من المعلومات، راجع كيفية استخدام الهويات المدارة للوصول إلى تكوين التطبيق.

يوصى بإنشاء التطبيق وتشغيله محليًا

1. لإنشاء التطبيق باستخدام .NET CLI، قم بتشغيل الأمر التالي في الأمر shell:

   dotnet build
   

2. بعد اكتمال الإنشاء، استخدم الأمر التالي لتشغيل تطبيق الويب محليًا:

   dotnet run
   

3. افتح نافذة متصفح، وانتقل إلى http://localhost:5000، وهو عنوان URL الافتراضي لتطبيق الويب المستضاف محلياً.

   

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

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

هام

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

1. سجل الدخول إلى مدخل Microsoft Azure، وحدد Resource groups.
2. في المربع تصفية حسب الاسم ، أدخل اسم مجموعة الموارد الخاصة بك.
3. في قائمة النتائج، حدد اسم مجموعة الموارد لاستعراض نظرة عامة.
4. حدد Delete resource group.
5. يُطلب منك تأكيد حذف مجموعة الموارد. أدخل اسم مجموعة الموارد للتأكيد وحدد "Delete".

بعد بضع لحظات، يتم حذف مجموعة الموارد وكافة مواردها.

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

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

إعادة تحميل البيانات السرية والشهادات من Key Vault تلقائيا

لمعرفة كيفية استخدام الهوية المدارة لتبسيط الوصول إلى App Configuration وKey Vault، راجع البرنامج التعليمي التالي:

تكامل الهوية المدارة