مشاركة عبر

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

  • مقالة

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

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

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

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

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

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

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

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

    az login

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

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

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

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

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

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

    pip install azure-identity

  3. تثبيت مكتبة البيانات السرية بالمخزن الرئيسي:

    pip install azure-keyvault-secrets

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

  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 Secrets 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_secrets.py يحتوي على هذه التعليمات البرمجية.

import os
from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

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

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

secretName = input("Input a name for your secret > ")
secretValue = input("Input a value for your secret > ")

print(f"Creating a secret in {keyVaultName} called '{secretName}' with the value '{secretValue}' ...")

client.set_secret(secretName, secretValue)

print(" done.")

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

retrieved_secret = client.get_secret(secretName)

print(f"Your secret is '{retrieved_secret.value}'.")
print(f"Deleting your secret from {keyVaultName} ...")

poller = client.begin_delete_secret(secretName)
deleted_secret = poller.result()

print(" done.")

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

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

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

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

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

يجب التصريح بطلبات التطبيق إلى معظم خدمات 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 = SecretClient(vault_url=KVUri, credential=credential)

حفظ سر

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

client.set_secret(secretName, secretValue)

استدعاء set_secret بإنشاء مكالمة إلى API REST Azure للمخزن الرئيسي.

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

استرداد البيانات السرية

لقراءة البيانات السرية من المخزن الرئيسي، استخدم طريقة get_secret:

retrieved_secret = client.get_secret(secretName)

قيمة البيانات السرية موجودة في retrieved_secret.value .

يمكنك أيضا استرداد سر باستخدام الأمر Azure CLI az keyvault secret show أو Azure PowerShell cmdlet Get-AzKeyVaultSecret.

حذف سر

لحذف البيانات السرية، استخدم طريقة begin_delete_secret:

poller = client.begin_delete_secret(secretName)
deleted_secret = poller.result()

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

يمكنك التحقق من إزالة السر باستخدام الأمر Azure CLI az keyvault secret show أو Azure PowerShell cmdlet Get-AzKeyVaultSecret.

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

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

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

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

az group delete --resource-group myResourceGroup

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