مشاركة عبر

التشغيل السريع: مكتبة عميل شهادة Azure Key Vault ل .NET

  • مقالة

ابدأ مع مكتبة عميل شهادة Azure Key Vault لـ NET. Azure Key Vault عبارة عن خدمة سحابية توفر مخزناً آمناً للشهادات. يمكنك تخزين المفاتيح وكلمات المرور والشهادات والأسرار الأخرى بأمان. يمكن إنشاء مخازن مفاتيح Azure وإدارتها من خلال مدخل Microsoft Azure. في هذا التشغيل السريع، ستتعلم كيفية إنشاء الشهادات واستردادها وحذفها من مخزن مفاتيح Azure باستخدام مكتبة عميل .NET.

موارد مكتبة عميل Key Vault:

الوثائق المرجعية لواجهة برمجة التطبيقات | التعليمة البرمجية المصدر للمكتبة | الحزمة (NuGet)

لمزيد من المعلومات حول Key Vault والشهادات، راجع:

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

يستخدم dotnet هذا التشغيل السريع وAzure CLI.

الإعداد

تستخدم هذه البداية السريعة مكتبة Azure Identity مع Azure CLI لمصادقة المستخدم إلى Azure Services. يمكن للمطورين أيضاً استخدام Visual Studio أو Visual Studio Code لمصادقة مكالماتهم، وللحصول على مزيد من المعلومات، راجع مصادقة العميل باستخدام مكتبة عميل Azure Identity.

تسجيل الدخول إلى Azure

  1. تشغيل الأمر login.

    az login

    في حال كان CLI يمكن فتح المستعرض الافتراضي الخاص بك، فإنه سيتم القيام بذلك وتحميل صفحة تسجيل الدخول Azure.

    بخلاف ذلك، افتح صفحة متصفح على https://aka.ms/devicelogin وأدخل رمز التفويض المعروض في جهازك.

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

امنح حق الوصول إلى خزنة المفاتيح الخاصة بك

للحصول على أذونات إلى مخزن المفاتيح الخاص بك من خلال التحكم في الوصول المستند إلى الدور (RBAC)، قم بتعيين دور إلى "اسم المستخدم الأساسي" (UPN) باستخدام الأمر Azure CLI az role assignment create.

az role assignment create --role "Key Vault Certificate Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

استبدل <upn>، <subscription-id>، <resource-group-name> و <your-unique-keyvault-name> بقيمك الفعلية. سيكون UPN الخاص بك عادة بتنسيق عنوان بريد إلكتروني (على سبيل المثال، username@domain.com).

إنشاء تطبيق وحدة تحكم .NET جديد

  1. في shell command، قم بتشغيل الأمر التالي لإنشاء مشروع باسم key-vault-console-app:

    dotnet new console --name key-vault-console-app

  2. غيّر إلى دليل key-vault-console-app الذي تم إنشاؤه حديثاً، وقم بتشغيل الأمر التالي لإنشاء المشروع:

    dotnet build

    يجب ألا يحتوي إخراج البناء على تحذيرات أو أخطاء.

    Build succeeded.
 0 Warning(s)
 0 Error(s)

قم بتثبيت الحِزَم

من shell الأوامر، ثبّت مكتبة عميل شهادة Azure Key Vault لـ NET.:

dotnet add package Azure.Security.KeyVault.Certificates

لهذا التشغيل السريع، ستحتاج أيضا إلى تثبيت مكتبة عميل Azure Identity:

dotnet add package Azure.Identity

تعيين متغيرات البيئة

يحصل التطبيق على اسم مخزن المفاتيح من متغير بيئة يسمى KEY_VAULT_NAME.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS أو Linux

export KEY_VAULT_NAME=<your-key-vault-name>

نموذج الكائن

تتيح لك مكتبة عميل شهادة Azure Key Vault لـ NET. إدارة الشهادات. يوضح قسم أمثلة التعليمة البرمجية كيفية إنشاء عميل وتعيين شهادة واسترداد شهادة وحذف شهادة.

أمثلة على التعليمات البرمجية

أضف توجيهات

أضف التوجيهات التالية إلى أعلى Program.cs:

using System;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

مصادقة عميل وإنشاؤه

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

في هذا التشغيل السريع، DefaultAzureCredential يصادق على key vault باستخدام بيانات اعتماد مستخدم التطوير المحلي الذي سجل الدخول إلى Azure CLI. عند نشر التطبيق إلى Azure، يمكن لنفس DefaultAzureCredential التعليمات البرمجية اكتشاف واستخدام هوية مدارة تلقائيا تم تعيينها إلى App Service أو Virtual Machine أو خدمات أخرى. لمزيد من المعلومات، راجع نظرة عامة على الهوية المُدارة.

في هذا المثال، يتم توسيع اسم مخزن المفاتيح الخاص بك إلى URI لمخزن المفاتيح، بالتنسيق https://<your-key-vault-name>.vault.azure.net. لمزيد من المعلومات حول المصادقة إلى مخزن المفاتيح، راجع دليل المطور.

string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = "https://" + keyVaultName + ".vault.azure.net";

var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

حفظ شهادة

في هذا المثال، من أجل التبسيط، يمكنك استخدام شهادة موقعة ذاتياً مع نهج الإصدار الافتراضية. لهذه المهمة، استخدم طريقة StartCreateCertificateAsync. تقبل معلمات الطريقة اسم الشهادة وcertificate policy.

var operation = await client.StartCreateCertificateAsync("myCertificate", CertificatePolicy.Default);
var certificate = await operation.WaitForCompletionAsync();

إشعار

إذا كان اسم الشهادة موجوداً، فسيقوم الرمز أعلاه بإنشاء إصدار جديد من تلك الشهادة.

استرجاع الشهادة

يمكنك الآن استرداد الشهادة التي تم إنشاؤها مسبقاً باستخدام طريقة GetCertificateAsync.

var certificate = await client.GetCertificateAsync("myCertificate");

حذف شهادة

أخيراً، دعنا نحذف الشهادة من مخزن المفاتيح ونزيلها باستخدام الأسلوبين StartDeleteCertificateAsync وPurgeDeletedCertificateAsync.

var operation = await client.StartDeleteCertificateAsync("myCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
await operation.WaitForCompletionAsync();

var certificate = operation.Value;
await client.PurgeDeletedCertificateAsync("myCertificate");

التعليمة البرمجية العينة

تعديل تطبيق وحدة تحكم .NET للتفاعل مع Key Vault عن طريق إكمال الخطوات التالية:

  • استبدل التعليمة البرمجية في Program.cs بالتعليمة البرمجية التالية:

    using System;
using System.Threading.Tasks;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string certificateName = "myCertificate";
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.Write($"Creating a certificate in {keyVaultName} called '{certificateName}' ...");
            CertificateOperation operation = await client.StartCreateCertificateAsync(certificateName, CertificatePolicy.Default);
            await operation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.WriteLine($"Retrieving your certificate from {keyVaultName}.");
            var certificate = await client.GetCertificateAsync(certificateName);
            Console.WriteLine($"Your certificate version is '{certificate.Value.Properties.Version}'.");

            Console.Write($"Deleting your certificate from {keyVaultName} ...");
            DeleteCertificateOperation deleteOperation = await client.StartDeleteCertificateAsync(certificateName);
            // You only need to wait for completion if you want to purge or recover the certificate.
            await deleteOperation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.Write($"Purging your certificate from {keyVaultName} ...");
            await client.PurgeDeletedCertificateAsync(certificateName);
            Console.WriteLine(" done.");
        }
    }
}

الاختبار والتحقق

تنفيذ الأمر التالي لبناء المشروع

dotnet build

يظهر تباين الإخراج التالي:

Creating a certificate in mykeyvault called 'myCertificate' ... done.
Retrieving your certificate from mykeyvault.
Your certificate version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your certificate from mykeyvault ... done
Purging your certificate from mykeyvault ... done

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

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

لمعرفة المزيد حول Key Vault وكيفية تكامله مع تطبيقاتك، راجع المقالات التالية: