مشاركة عبر

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

  • مقالة

البدء مع مكتبة العميل Azure Key Vault لـ Python. يُرجى اتباع هذه الخطوات لتثبيت الحزمة وتجربة التعليمات البرمجية للمهام الأساسية. باستخدام "Key Vault" لتخزين مفاتيح التشفير، يمكنك تجنب تخزين هذه المفاتيح في التعليمات البرمجية، ما يزيد من أمان تطبيقك.

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

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

يفترض التشغيل السريع أنك تقوم بتشغيل Azure CLI أو Azure PowerShell في نافذة terminal لـ Linux.

إعداد البيئة المحلية

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

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

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

    az login

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

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

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

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

  1. في terminal أو موجه الأوامر، بادر بإنشاء مجلد مشروع مناسب، ثم بادر بإنشاء بيئة Python الافتراضية وتنشيطها كما هو موضح في استخدام بيئات Python الظاهرية.

  2. تثبيت مكتبة هوية Microsoft Entra:

    pip install azure-identity

  3. تثبيت مكتبة عميل Key Vault الرئيسي:

    pip install azure-keyvault-keys

إنشاء مجموعة موارد ومخزن رئيسي

  1. استخدم الأمر az group create لإنشاء مجموعة موارد:

    az group create --name myResourceGroup --location eastus

    يمكنك تغيير "إيستوس" إلى موقع قريب منك، إذا كنت تفضل ذلك.

  2. استخدم az keyvault create لإنشاء خزنة المفاتيح:

    az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroup

    استبدل <your-unique-keyvault-name> باسم فريد عبر Azure بالكامل. عادة ما تستخدم اسمك الشخصي أو اسم الشركة مع أرقام ومعرفات أخرى.

قم بتعيين المتغير البيئي KEY_VAULT_NAME

سيستخدم برنامجنا النصي القيمة المعينة KEY_VAULT_NAME لمتغير البيئة كاسم لخزنة المفتاح. ولذلك يجب عليك تعيين هذه القيمة باستخدام الأمر التالي:

export KEY_VAULT_NAME=<your-unique-keyvault-name>

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

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

az role assignment create --role "Key Vault Crypto 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).

إنشاء نموذج التعليمات البرمجية

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

إنشاء ملف يسمى kv_keys.py يحتوي على هذه التعليمات البرمجية.

import os
from azure.keyvault.keys import KeyClient
from azure.identity import DefaultAzureCredential

keyVaultName = os.environ["KEY_VAULT_NAME"]
KVUri = "https://" + keyVaultName + ".vault.azure.net"

credential = DefaultAzureCredential()
client = KeyClient(vault_url=KVUri, credential=credential)

keyName = input("Input a name for your key > ")

print(f"Creating a key in {keyVaultName} called '{keyName}' ...")

rsa_key = client.create_rsa_key(keyName, size=2048)

print(" done.")

print(f"Retrieving your key from {keyVaultName}.")

retrieved_key = client.get_key(keyName)

print(f"Key with name '{retrieved_key.name}' was found.")
print(f"Deleting your key from {keyVaultName} ...")

poller = client.begin_delete_key(keyName)
deleted_key = poller.result()

print(" done.")

تشغيل التعليمات البرمجية

تأكد من أن التعليمات البرمجية في المقطع السابق موجودة في ملف يسمى kv_keys.py. ثم قم بتشغيل التعليمات البرمجية باستخدام الأمر التالي:

python kv_keys.py

قد تؤدي إعادة تشغيل التعليمات البرمجية بنفس اسم المفتاح إلى ظهور الخطأ ، "(تعارض) اسم> المفتاح <حاليا في حالة محذوفة ولكن قابلة للاسترداد." استخدم اسم مفتاح مختلف.

تفاصيل التعليمات البرمجية

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

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

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

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

credential = DefaultAzureCredential()
client = KeyClient(vault_url=KVUri, credential=credential)

حفظ مفتاح

بمجرد الحصول على كائن العميل لخزنة المفاتيح، يمكنك تخزين مفتاح باستخدام طريقة create_rsa_key:

rsa_key = client.create_rsa_key(keyName, size=2048)

يمكنك أيضا استخدام أسلوب create_key أو أسلوب create_ec_key.

استدعاء create بإنشاء أسلوب إلى API REST Azure للمخزن الرئيسي.

عندما يعالج Azure الطلب، فإنه يصادق هوية المتصل (كيان الخدمة) باستخدام كائن بيانات الاعتماد الذي قدمته للعميل.

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

لقراءة مفتاح من Key Vault استخدم طريقة get_key:

retrieved_key = client.get_key(keyName)

يمكنك أيضا التحقق من تعيين المفتاح باستخدام الأمر Azure CLI az keyvault key show أو Azure PowerShell cmdlet Get-AzKeyVaultKey.

حذف مفتاح

لحذف مفتاح، استخدم أسلوب begin_delete_key:

poller = client.begin_delete_key(keyName)
deleted_key = poller.result()

تعد الطريقة begin_delete_key غير متزامنة وتقوم بإرجاع كائن أداة التحقق. استدعاء طريقة أداة التحقق result في انتظار اكتمالها.

يمكنك التحقق من حذف المفتاح باستخدام الأمر Azure CLI az keyvault key show أو Azure PowerShell cmdlet Get-AzKeyVaultKey.

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

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

إذا كنت تريد أيضاً تجربة الشهادات والأسرار، فيمكنك إعادة استخدام المخزن الرئيسي الذي تم إنشاؤه طبقاً لهذه الخطوات.

وفي حالة عدم حدوث ذلك، فعند الانتهاء من الموارد التي تم إنشاؤها طبقاً لهذه الخطوات، استخدم الأمر التالي لحذف مجموعة الموارد وجميع الموارد المضمنة بها:

az group delete --resource-group myResourceGroup

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