مشاركة عبر

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

  • مقالة

قم بالشروع في العمل مع مكتبة عميل مفتاح Azure Key Vault لـ .NET. Azure Key Vault عبارة عن خدمة سحابة توفر مخزنًا آمنًا لمفاتيح التشفير. يمكنك تخزين مفاتيح التشفير وكلمات المرور والشهادات والأسرار الأخرى بشكل آمن. يمكن إنشاء مخازن مفاتيح Azure وإدارتها من خلال مدخل Microsoft Azure. في البدء السريع هذا، تتعرف على كيفية إنشاء المفاتيح واستردادها وحذفها من Azure key vault باستخدام مكتبة عميل مفتاح .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)، قم بتعيين دور باستخدام الأمر Azure CLI az role assignment create.

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

استبدل <app-id>و <resource-group-name><subscription-id>و <your-unique-keyvault-name> بقيمك الفعلية. <app-id> هو معرف التطبيق (العميل) للتطبيق المسجل في Microsoft Entra.

إنشاء تطبيق وحدة تحكم .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)

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

من command shell، قم بتثبيت مكتبة عميل مفتاح Azure Key Vault لـ .NET:

dotnet add package Azure.Security.KeyVault.Keys

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

dotnet add package Azure.Identity

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

يستخدم هذا التطبيق اسم key vault كمتغير بيئة يُسمى 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.Keys;

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

يجب التصريح بطلبات التطبيق إلى معظم خدمات 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. لمزيد من المعلومات حول المصادقة إلى مخزن المفاتيح، راجع دليل المطور.

var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = $"https://{keyVaultName}.vault.azure.net";

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

حفظ مفتاح

لهذه المهمة، استخدم الأسلوب CreateKeyAsync. تقبل معلمات الأسلوب اسم مفتاح ونوع المفتاح.

var key = await client.CreateKeyAsync("myKey", KeyType.Rsa);

إشعار

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

استرداد مفتاح

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

var key = await client.GetKeyAsync("myKey");

حذف مفتاح

أخيرًا، دعنا نحذف المفتاح من key vault ومسحه باستخدام الأسلوبين StartDeleteKeyAsync وPurgeDeletedKeyAsync.

var operation = await client.StartDeleteKeyAsync("myKey");

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

var key = operation.Value;
await client.PurgeDeletedKeyAsync("myKey");

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

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

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

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

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

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

            Console.Write($"Creating a key in {keyVaultName} called '{keyName}' ...");
            var createdKey = await client.CreateKeyAsync(keyName, KeyType.Rsa);
            Console.WriteLine("done.");

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

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

            Console.Write($"Purging your key from {keyVaultName} ...");
            await client.PurgeDeletedKeyAsync(keyName);
            Console.WriteLine(" done.");
        }
    }
}

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

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

    dotnet build

  2. نفذ الأمر التالي لتشغيل التطبيق.

    dotnet run

  3. عند مطالبتك قم بإدخال قيمة سرية. على سبيل المثال، mySecretPassword.

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

    Creating a key in mykeyvault called 'myKey' ... done.
Retrieving your key from mykeyvault.
Your key version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your key from jl-kv ... done
Purging your key from <your-unique-keyvault-name> ... done.

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

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

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