مكتبة عميل Azure Identity ل Python - الإصدار 1.14.1

توفر مكتبة Azure Identity دعم مصادقة الرمز المميز ل Azure Active Directory (Azure AD) عبر Azure SDK. يوفر مجموعة من TokenCredential عمليات التنفيذ، والتي يمكن استخدامها لإنشاء عملاء Azure SDK الذين يدعمون مصادقة الرمز المميز Azure AD.

التعليمات البرمجية | المصدرالحزمة (PyPI) | حزمة (Conda) | الوثائق | المرجعية لواجهة برمجة التطبيقاتوثائق Azure AD

الشروع في العمل

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

تثبيت هوية Azure باستخدام pip:

pip install azure-identity

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

• اشتراك Azure
• Python 3.7 أو إصدار حديث من Python 3 (لا تدعم هذه المكتبة إصدارات نهاية العمر الافتراضي)

المصادقة أثناء التطوير المحلي

عند تصحيح الأخطاء وتنفيذ التعليمات البرمجية محليا، من المعتاد أن يستخدم المطورون حساباتهم الخاصة لمصادقة المكالمات إلى خدمات Azure. تدعم مكتبة Azure Identity المصادقة من خلال أدوات المطور لتبسيط التطوير المحلي.

المصادقة عبر Visual Studio Code

يمكن للمطورين الذين يستخدمون Visual Studio Code استخدام ملحق حساب Azure للمصادقة عبر المحرر. يمكن للتطبيقات التي تستخدم DefaultAzureCredential أو VisualStudioCodeCredential يمكنها بعد ذلك استخدام هذا الحساب لمصادقة المكالمات في تطبيقها عند التشغيل محليا.

للمصادقة في Visual Studio Code، تأكد من تثبيت ملحق حساب Azure. بمجرد التثبيت، افتح لوحة الأوامر وقم بتشغيل الأمر Azure: Sign In .

إنها مشكلةVisualStudioCodeCredential معروفة لا تعمل مع إصدارات ملحق حساب Azure الأحدث من 0.9.11. هناك إصلاح طويل الأجل لهذه المشكلة قيد التقدم. في غضون ذلك، ضع في اعتبارك المصادقة عبر Azure CLI.

المصادقة عبر Azure CLI

DefaultAzureCredentialAzureCliCredential ويمكنه المصادقة كمستخدم سجل الدخول إلى Azure CLI. لتسجيل الدخول إلى Azure CLI، قم بتشغيل az login. على نظام مع مستعرض ويب افتراضي، سيقوم Azure CLI بتشغيل المستعرض لمصادقة مستخدم.

عندما لا يتوفر مستعرض افتراضي، az login سيستخدم تدفق مصادقة التعليمات البرمجية للجهاز. يمكن أيضا تحديد هذا التدفق يدويا عن طريق تشغيل az login --use-device-code.

المصادقة عبر Azure Developer CLI

يمكن للمطورين الترميز خارج IDE أيضا استخدام Azure Developer CLI للمصادقة. يمكن للتطبيقات التي تستخدم DefaultAzureCredential أو AzureDeveloperCliCredential بعد ذلك استخدام هذا الحساب لمصادقة المكالمات في تطبيقها عند التشغيل محليًا.

للمصادقة باستخدام Azure Developer CLI، يمكن للمستخدمين تشغيل الأمر azd auth login. بالنسبة للمستخدمين الذين يعملون على نظام مع مستعرض ويب افتراضي، سيقوم Azure Developer CLI بتشغيل المستعرض لمصادقة المستخدم.

بالنسبة للأنظمة التي لا تحتوي على مستعرض ويب افتراضي، سيستخدم الأمر azd auth login --use-device-code تدفق مصادقة رمز الجهاز.

المفاهيم الرئيسية

بيانات الاعتماد

بيانات الاعتماد هي فئة تحتوي على البيانات المطلوبة لعميل الخدمة لمصادقة الطلبات أو يمكنها الحصول عليها. يقبل عملاء الخدمة عبر Azure SDK مثيل بيانات اعتماد عند إنشائها، ويستخدمون بيانات الاعتماد هذه لمصادقة الطلبات.

تركز مكتبة Azure Identity على مصادقة OAuth مع Azure AD. يوفر فئات بيانات اعتماد مختلفة قادرة على الحصول على رمز مميز للوصول Azure AD. راجع قسم الاعتماد أدناه للحصول على قائمة بفئات بيانات اعتماد هذه المكتبة.

DefaultAzureCredential

DefaultAzureCredential مناسب لمعظم التطبيقات التي سيتم تشغيلها في Azure لأنه يجمع بين بيانات اعتماد الإنتاج الشائعة وبيانات اعتماد التطوير. DefaultAzureCredential محاولات المصادقة عبر الآليات التالية، بهذا الترتيب، تتوقف عند نجاح واحد:

ملاحظة: DefaultAzureCredential يهدف إلى تبسيط بدء استخدام المكتبة عن طريق التعامل مع السيناريوهات الشائعة مع سلوكيات افتراضية معقولة. يجب على المطورين الذين يريدون المزيد من التحكم أو الذين لا يتم تقديم سيناريوهم بواسطة الإعدادات الافتراضية استخدام أنواع بيانات اعتماد أخرى.

1. البيئه - DefaultAzureCredential سيقرأ معلومات الحساب المحددة عبر البيئة واستخدامها للمصادقة.
2. هوية حمل العمل - إذا تم نشر التطبيق في خدمة Azure Kubernetes مع تمكين الهوية المدارة، DefaultAzureCredential فسيتم المصادقة معه.
3. الهوية المدارة - إذا تم نشر التطبيق إلى مضيف Azure مع تمكين الهوية المدارة، DefaultAzureCredential فسيتم المصادقة معه.
4. Azure CLI - إذا قام مستخدم بتسجيل الدخول عبر أمر Azure CLI az login ، DefaultAzureCredential فسيصادق على أنه هذا المستخدم.
5. Azure PowerShell - إذا قام مستخدم بتسجيل الدخول عبر أمر Azure PowerShell Connect-AzAccount ، DefaultAzureCredential فسيصادق على أنه هذا المستخدم.
6. Azure Developer CLI - إذا قام المطور بالمصادقة عبر أمر Azure Developer CLI azd auth login ، DefaultAzureCredential فسيتم المصادقة باستخدام هذا الحساب.
7. المتصفح التفاعلي - إذا تم تمكينه، DefaultAzureCredential فسيصادق المستخدم بشكل تفاعلي عبر المستعرض الافتراضي. يتم تعطيل نوع بيانات الاعتماد هذا بشكل افتراضي.

ملاحظة حول VisualStudioCodeCredential

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

أمثلة

يتم توفير الأمثلة التالية أدناه:

• المصادقة باستخدام DefaultAzureCredential
• تعريف تدفق مصادقة مخصص باستخدام ChainedTokenCredential
• بيانات الاعتماد غير المتزامنة

المصادقة باستخدام DefaultAzureCredential

يمكن العثور على مزيد من التفاصيل حول تكوين بيئتك لاستخدام في DefaultAzureCredentialالوثائق المرجعية للفئة.

يوضح هذا المثال مصادقة BlobServiceClient من مكتبة azure-storage-blob باستخدام DefaultAzureCredential.

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

تمكين المصادقة التفاعلية باستخدام DefaultAzureCredential

يتم تعطيل المصادقة التفاعلية DefaultAzureCredential بشكل افتراضي ويمكن تمكينها باستخدام وسيطة كلمة أساسية:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

عند التمكين، DefaultAzureCredential يعود إلى المصادقة التفاعلية عبر مستعرض الويب الافتراضي للنظام عندما لا تتوفر بيانات اعتماد أخرى.

تحديد هوية مدارة يعينها المستخدم ل DefaultAzureCredential

يسمح العديد من مضيفي Azure بتعيين هوية مدارة يعينها المستخدم. للتكوين DefaultAzureCredential لمصادقة هوية معينة من قبل المستخدم، استخدم وسيطة managed_identity_client_id الكلمة الأساسية:

DefaultAzureCredential(managed_identity_client_id=client_id)

بدلا من ذلك، قم بتعيين متغير AZURE_CLIENT_ID البيئة إلى معرف عميل الهوية.

تعريف تدفق مصادقة مخصص باستخدام ChainedTokenCredential

DefaultAzureCredential بشكل عام أسرع طريقة للبدء في تطوير التطبيقات ل Azure. بالنسبة للسيناريوهات الأكثر تقدما، يربط ChainedTokenCredential مثيلات بيانات اعتماد متعددة لتجربتها بالتسلسل عند المصادقة. سيحاول كل بيانات اعتماد متسلسلة بدوره حتى يوفر رمزا مميزا أو يفشل في المصادقة بسبب خطأ.

يوضح المثال التالي إنشاء بيانات اعتماد ستحاول أولا المصادقة باستخدام الهوية المدارة. ستعود بيانات الاعتماد إلى المصادقة عبر Azure CLI عندما تكون الهوية المدارة غير متوفرة. يستخدم EventHubProducerClient هذا المثال من مكتبة عميل azure-eventhub .

from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential

managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)

client = EventHubProducerClient(namespace, eventhub_name, credential_chain)

بيانات الاعتماد غير المتزامنة

تتضمن هذه المكتبة مجموعة من واجهات برمجة التطبيقات غير المتزامنة. لاستخدام بيانات الاعتماد غير المتزامنة في azure.identity.aio، يجب أولا تثبيت نقل غير متزامن، مثل aiohttp. لمزيد من المعلومات، راجع وثائق azure-core.

يجب إغلاق بيانات الاعتماد غير المتزامنة عندما لا تكون هناك حاجة إليها. كل بيانات اعتماد غير متزامنة هي مدير سياق غير متزامن وتحدد أسلوبا غير متزامن close . على سبيل المثال:

from azure.identity.aio import DefaultAzureCredential

# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()

# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
  ...

يوضح هذا المثال مصادقة البيانات غير SecretClient المتزامنة من azure-keyvault-secrets باستخدام بيانات اعتماد غير متزامنة.

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

default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)

دعم الهوية المدارة

يتم دعم مصادقة الهوية المدارة إما DefaultAzureCredential عبر أو ManagedIdentityCredential مباشرة لخدمات Azure التالية:

• Azure App Service وAzure Functions
• Azure Arc
• Azure Cloud Shell
• ⁧⁩Azure Kubernetes Service⁧⁩
• Azure Service Fabric
• أجهزة Azure الظاهرية
• مجموعات مقياس أجهزة Azure الظاهرية

أمثلة

المصادقة باستخدام هوية مدارة يعينها المستخدم

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)

المصادقة باستخدام هوية مدارة معينة من قبل النظام

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)

التكوين السحابي

بيانات الاعتماد الافتراضية للمصادقة على نقطة النهاية Azure AD ل Azure Public Cloud. للوصول إلى الموارد في السحب الأخرى، مثل Azure Government أو سحابة خاصة، قم بتكوين بيانات الاعتماد باستخدام الوسيطة authority . يحدد AzureAuthorityHosts المراجع للسحب المعروفة:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

إذا لم تكن سلطة السحابة الخاصة بك مدرجة في AzureAuthorityHosts، يمكنك تحديد عنوان URL الخاص بها بشكل صريح:

DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")

كبديل لتحديد الوسيطة authority ، يمكنك أيضا تعيين AZURE_AUTHORITY_HOST متغير البيئة إلى عنوان URL لمرجع السحابة. هذا الأسلوب مفيد عند تكوين بيانات اعتماد متعددة للمصادقة على نفس السحابة:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

لا تتطلب جميع بيانات الاعتماد هذا التكوين. تستخدم بيانات الاعتماد التي تصادق من خلال أداة تطوير، مثل AzureCliCredential، تكوين هذه الأداة. وبالمثل، VisualStudioCodeCredential يقبل وسيطة ولكنه يتم تعيينه افتراضيا authority إلى المرجع الذي يطابق إعداد "Azure: Cloud" الخاص ب VS Code.

فئات بيانات الاعتماد

مصادقة التطبيقات المستضافة من Azure

بيانات اعتماد	الاستخدام
DefaultAzureCredential	يوفر تجربة مصادقة مبسطة لبدء تطوير التطبيقات التي تعمل بسرعة في Azure.
ChainedTokenCredential	يسمح للمستخدمين بتحديد تدفقات المصادقة المخصصة التي تنشئ بيانات اعتماد متعددة.
EnvironmentCredential	يصادق على مدير الخدمة أو المستخدم عبر معلومات بيانات الاعتماد المحددة في متغيرات البيئة.
ManagedIdentityCredential	يصادق على الهوية المدارة لمورد Azure.
WorkloadIdentityCredential	يدعم هوية حمل العمل Azure AD على Kubernetes.

مصادقة كيانات الخدمة

بيانات اعتماد	الاستخدام	‏‏المرجع
CertificateCredential	يصادق على أصل خدمة باستخدام شهادة.	مصادقة كيان الخدمة
ClientAssertionCredential	مصادقة كيان خدمة باستخدام تأكيد عميل موقع.
ClientSecretCredential	يصادق على مدير الخدمة باستخدام سر.	مصادقة كيان الخدمة

مصادقة المستخدمون

بيانات اعتماد	الاستخدام	‏‏المرجع
AuthorizationCodeCredential	مصادقة مستخدم برمز تخويل تم الحصول عليه مسبقا.	رمز مصادقة OAuth2
DeviceCodeCredential	يقوم بمصادقة مستخدم بشكل تفاعلي على الأجهزة ذات واجهة المستخدم المحدودة.	مصادقة رمز الجهاز
InteractiveBrowserCredential	مصادقة مستخدم بشكل تفاعلي باستخدام مستعرض النظام الافتراضي.	رمز مصادقة OAuth2
OnBehalfOfCredential	نشر هوية المستخدم المفوض والأذونات من خلال سلسلة الطلبات.	نيابة عن المصادقة
UsernamePasswordCredential	مصادقة مستخدم باسم مستخدم وكلمة مرور (لا يدعم المصادقة متعددة العوامل).	مصادقة اسم المستخدم + كلمة المرور

المصادقة عبر أدوات التطوير

بيانات اعتماد	الاستخدام	‏‏المرجع
AzureCliCredential	المصادقة في بيئة تطوير باستخدام Azure CLI.	مصادقة Azure CLI
AzureDeveloperCliCredential	المصادقة في بيئة تطوير باستخدام Azure Developer CLI.	مرجع Azure Developer CLI
AzurePowerShellCredential	المصادقة في بيئة تطوير باستخدام Azure PowerShell.	مصادقة Azure PowerShell
VisualStudioCodeCredential	المصادقة كمستخدم سجل الدخول إلى ملحق حساب Azure Visual Studio Code.	ملحق حساب VS Code Azure

متغيرات البيئة.

يمكن تكوين DefaultAzureCredential و EnvironmentCredential مع متغيرات البيئة. يتطلب كل نوع من أنواع المصادقة قيما لمتغيرات محددة:

كيان الخدمة مع بيانات سرية

اسم المتغير	القيمة
AZURE_CLIENT_ID	معرف تطبيق Azure AD
AZURE_TENANT_ID	معرف مستأجر Azure AD للتطبيق
AZURE_CLIENT_SECRET	أحد أسرار عميل التطبيق

كيان الخدمة مع شهادة

اسم المتغير	القيمة
AZURE_CLIENT_ID	معرف تطبيق Azure AD
AZURE_TENANT_ID	معرف مستأجر Azure AD للتطبيق
AZURE_CLIENT_CERTIFICATE_PATH	المسار إلى ملف شهادة PEM أو PKCS12 بما في ذلك المفتاح الخاص
AZURE_CLIENT_CERTIFICATE_PASSWORD	كلمة مرور ملف الشهادة، إن وجدت

اسم المستخدم وكلمة المرور

اسم المتغير	القيمة
AZURE_CLIENT_ID	معرف تطبيق Azure AD
AZURE_USERNAME	اسم مستخدم (عادة ما يكون عنوان بريد إلكتروني)
AZURE_PASSWORD	كلمة مرور ذلك المستخدم

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

التخزين المؤقت للرمز المميز

التخزين المؤقت للرمز المميز هو ميزة توفرها مكتبة Azure Identity التي تسمح للتطبيقات ب:

• الرموز المميزة لذاكرة التخزين المؤقت في الذاكرة (افتراضي) أو على القرص (الاشتراك).
• تحسين المرونة والأداء.
• تقليل عدد الطلبات المقدمة إلى Azure AD للحصول على رموز الوصول المميزة.

توفر مكتبة Azure Identity كلا من التخزين المؤقت في الذاكرة والقرص الثابت. لمزيد من التفاصيل، راجع وثائق التخزين المؤقت للرمز المميز.

استكشاف الأخطاء وإصلاحها

راجع دليل استكشاف الأخطاء وإصلاحها للحصول على تفاصيل حول كيفية تشخيص سيناريوهات الفشل المختلفة.

معالجة الأخطاء

ترفع CredentialUnavailableError بيانات الاعتماد عندما لا تتمكن من محاولة المصادقة لأنها تفتقر إلى البيانات أو الحالة المطلوبة. على سبيل المثال، سيرفع EnvironmentCredential هذا الاستثناء عندما يكون غير مكتمل.

ترتفع بيانات الاعتماد azure.core.exceptions.ClientAuthenticationError عندما تفشل في المصادقة. ClientAuthenticationError لديه سمة message ، والتي تصف سبب فشل المصادقة. عند رفعها بواسطة DefaultAzureCredential أو ChainedTokenCredential، تجمع الرسالة رسائل خطأ من كل بيانات اعتماد في السلسلة.

لمزيد من المعلومات حول معالجة أخطاء Azure AD معينة، راجع وثائق رمز الخطأ Azure AD.

تسجيل الدخول

تستخدم هذه المكتبة مكتبة التسجيل القياسية للتسجيل. تسجل بيانات الاعتماد المعلومات الأساسية، بما في ذلك جلسات HTTP (عناوين URL والعناوين وما إلى ذلك) على مستوى INFO. لا تحتوي إدخالات السجل هذه على أسرار المصادقة.

لا يتم تمكين تسجيل مستوى DEBUG التفصيلي، بما في ذلك أجسام الطلب/الاستجابة وقيم العنوان، بشكل افتراضي. يمكن تمكينه باستخدام الوسيطة logging_enable . على سبيل المثال:

credential = DefaultAzureCredential(logging_enable=True)

تنبيه: تحتوي سجلات مستوى تتبع الأخطاء من بيانات الاعتماد على معلومات حساسة. يجب حماية هذه السجلات لتجنب المساس بأمان الحساب.

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

دعم مكتبة العميل

تقبل مكتبات العميل والإدارة المدرجة في صفحة إصدار Azure SDK التي تدعم مصادقة Azure AD بيانات الاعتماد من هذه المكتبة. يمكنك معرفة المزيد حول استخدام هذه المكتبات في وثائقها، والتي ترتبط من صفحة الإصدار.

المشكلات المعروفة

لا تدعم هذه المكتبة Azure AD B2C.

بالنسبة للمشكلات المفتوحة الأخرى، راجع مستودع GitHub الخاص بالمكتبة.

تقديم ملاحظات

إذا واجهت أخطاء أو كان لديك اقتراحات، فافتح مشكلة.

المساهمة

هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. لمزيد من التفاصيل، قم بزيارة https://cla.microsoft.com.

عند إرسال طلب سحب، سيحدد روبوت CLA-bot تلقائيًا ما إذا كنت بحاجة إلى تقديم CLA وتزيين العلاقات العامة بشكل مناسب (على سبيل المثال، التسمية أو التعليق). ما عليك سوى اتباع التعليمات التي يقدمها الروبوت. ستحتاج فقط إلى القيام بذلك مرة واحدة عبر جميع المستودعات باستخدام CLA لدينا.

اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة الشائعة حول مدونة قواعد السلوك أو الاتصال بأي أسئلة أو تعليقات opencode@microsoft.com إضافية.