مشاركة عبر

التشغيل السريع: مكتبة عميل شهادة مخزن مفاتيح Azure لـ Python

  • مقالة

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

الوثائق المرجعية لواجهة برمجة التطبيقات (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. في محطة طرفية أو موجه الأوامر، قم بإنشاء مجلد مشروع مناسب، ثم قم بإنشاء بيئة Python الافتراضية وتنشيطها كما هو موضح في استخدام بيئات Python الافتراضية

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

    pip install azure.identity

  3. تثبيت مكتبة عميل شهادة Key Vault:

    pip install azure-keyvault-certificates

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

  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 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).

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

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

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

import os
from azure.keyvault.certificates import CertificateClient, CertificatePolicy
from azure.identity import DefaultAzureCredential

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

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

certificateName = input("Input a name for your certificate > ")

print(f"Creating a certificate in {keyVaultName} called '{certificateName}' ...")

policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()

print(" done.")

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

retrieved_certificate = client.get_certificate(certificateName)

print(f"Certificate with name '{retrieved_certificate.name}' was found'.")
print(f"Deleting your certificate from {keyVaultName} ...")

poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()

print(" done.")

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

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

python kv_certificates.py
  • إذا واجهت أخطاء أذونات، فتأكد من تشغيل az keyvault set-policy أو Set-AzKeyVaultAccessPolicy الأمر.
  • قد تؤدي إعادة تشغيل التعليمات البرمجية بنفس اسم المفتاح إلى ظهور الخطأ ، "(تعارض) اسم> الشهادة <حاليا في حالة محذوفة ولكنها قابلة للاسترداد." استخدم اسم مفتاح مختلف.

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

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

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

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

حفظ شهادة

بمجرد الحصول على كائن العميل لخزنة المفاتيح، يمكنك إنشاء شهادة باستخدام أسلوب begin_create_certificate:

policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()

هنا، تتطلب الشهادة نهج تم الحصول عليه باستخدام أسلوب CertificatePolicy.get_default.

استدعاء أسلوب بإنشاء استدعاء غير begin_create_certificate متزامن إلى API REST Azure لخزنة المفاتيح. استدعاء غير متزامن يقوم بإرجاع كائن أداة التحقق. لانتظار نتيجة العملية، اتصل result بطريقة أداة التحقق.

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

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

لقراءة شهادة من "Key Vault"، استخدم أسلوب get_certificate:

retrieved_certificate = client.get_certificate(certificateName)

يمكنك أيضا التحقق من تعيين الشهادة باستخدام الأمر Azure CLI az keyvault certificate show أو Azure PowerShell cmdlet Get-AzKeyVaultCertificate

حذف شهادة

لحذف شهادة، استخدم أسلوب begin_delete_certificate:

poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()

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

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

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

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

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

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

az group delete --resource-group myResourceGroup

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