Aracılığıyla paylaş

Python için Azure Kimlik kitaplığındaki kimlik bilgileri zincirleri

Azure Kimlik kitaplığı kimlik bilgileri sağlar. Azure Core kitaplığının TokenCredential protokolunu uygulayan genel sınıflar. Kimlik bilgisi, Microsoft Entra Id'den erişim belirteci almak için ayrı bir kimlik doğrulama akışını temsil eder. Bu kimlik bilgileri, denenecek sıralı bir kimlik doğrulama mekanizması dizisi oluşturmak için birbirine zincirlenebilir.

Zincirlenmiş kimlik bilgileri nasıl çalışır?

Çalışma zamanında, kimlik bilgisi zinciri dizinin ilk kimlik bilgilerini kullanarak kimlik doğrulaması yapmaya çalışır. Bu kimlik bilgisi bir erişim belirteci alamazsa, bir erişim belirteci başarıyla alınana kadar dizideki bir sonraki kimlik bilgisi denenir ve bu şekilde devam edilir. Aşağıdaki sıralı diyagramda bu davranış gösterilmektedir:

kimlik bilgisi zinciri sırasını gösteren Diyagramı.

Kimlik bilgisi zincirlerini neden kullanmalısınız?

Zincirlenmiş kimlik bilgileri aşağıdaki avantajları sunabilir:

  • Ortam tanıma: Uygulamanın çalıştığı ortama göre en uygun kimlik bilgilerini otomatik olarak seçer. Bu olmadan, aşağıdaki gibi bir kod yazmanız gerekir:

    # Set up credential based on environment (Azure or local development)
if os.getenv("WEBSITE_HOSTNAME"):
    credential = ManagedIdentityCredential(client_id=user_assigned_client_id)
else:
    credential = AzureCliCredential()

  • Sorunsuz geçişler: Uygulamanız, kimlik doğrulama kodunu değiştirmeden yerel geliştirmeden hazırlama veya üretim ortamınıza geçebilir.

  • Geliştirilmiş dayanıklılık: Önceki kimlik doğrulama yöntemi başarısız olduğunda devreye giren bir geri dönüş mekanizması içerir.

Zincirlenmiş kimlik bilgisi nasıl seçilir?

Kimlik bilgisi zincirlemenin iki farklı felsefesi vardır:

  • Bir zinciri "daha basit hale getirme": Önceden yapılandırılmış bir zincirle başlayın ve ihtiyacınız olmayanları hariç tutun. Bu yaklaşım için DefaultAzureCredential genel bakış bölümüne bakın.
  • Bir zinciri "derleyin": Boş bir zincirle başlayın ve yalnızca ihtiyacınız olanı ekleyin. Bu yaklaşım için ChainedTokenCredential genel bakış bölümüne bakın.

DefaultAzureCredential'a genel bakış

DefaultAzureCredential, belirli bir görüşe sahip, önceden yapılandırılmış bir kimlik bilgileri zinciridir. En yaygın kimlik doğrulama akışları ve geliştirici araçlarının yanı sıra birçok ortamı destekleyecek şekilde tasarlanmıştır. Grafik biçiminde, temel zincir şöyle görünür:

DefaultAzureCredential kimlik doğrulama akışını gösteren diyagram.

Kimlik bilgilerinin hangi sırayla denendiği DefaultAzureCredential aşağıda belirtilmiştir.

Sipariş Kimlik Belgesi Açıklama Varsayılan olarak etkinleştirilsin mi?
1 Ortam Uygulama hizmet sorumlusunun (uygulama kullanıcısı) uygulama için yapılandırılıp yapılandırılmadığını belirlemek için ortam değişkenlerinden oluşan bir koleksiyonu okur. Öyleyse, DefaultAzureCredential uygulamanın kimliğini Azure'da doğrulamak için bu değerleri kullanır. Bu yöntem genellikle sunucu ortamlarında kullanılır, ancak yerel olarak geliştirirken de kullanılabilir. Evet
2 İş Yükü Kimliği Uygulama İş Yükü Kimliği etkinleştirilmiş bir Azure konağına dağıtıldıysa bu hesabın kimliğini doğrula. Evet
3 Yönetilen Kimlik Uygulama Yönetilen Kimlik etkinleştirilmiş bir Azure konağına dağıtılırsa, bu Yönetilen Kimliği kullanarak uygulamanın kimliğini Azure'da doğrularsınız. Evet
4 Paylaşılan Belirteç Önbelleği Yalnızca Windows'ta, geliştirici Visual Studio'da oturum açarak Azure'da kimlik doğrulaması yaptıysa, aynı hesabı kullanarak uygulamanın kimliğini Azure'da doğrulayın. Evet
5 Azure CLI Geliştirici Azure CLI'nın komutunu kullanarak Azure'da az login kimlik doğrulaması yaptıysa, aynı hesabı kullanarak uygulamanın kimliğini Azure'da doğrular. Evet
6 Azure PowerShell Geliştirici Azure PowerShell'in cmdlet'ini kullanarak Azure'da Connect-AzAccount kimlik doğrulaması yaptıysa, aynı hesabı kullanarak uygulamanın kimliğini Azure'da doğrulayın. Evet
7 Azure Geliştirici CLI'sı Geliştirici, Azure Geliştirici CLI'sinin komutunu kullanarak Azure'da azd auth login kimlik doğrulaması yaptıysa, bu hesapla kimlik doğrulamasından geçin. Evet
8 Etkileşimli tarayıcı Etkinleştirilirse, geçerli sistemin varsayılan tarayıcısı aracılığıyla geliştiricinin kimliğini etkileşimli olarak doğrular. Hayır

En basit haliyle parametresiz sürümünü DefaultAzureCredential aşağıdaki gibi kullanabilirsiniz:

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

# Acquire a credential object
credential = DefaultAzureCredential()

blob_service_client = BlobServiceClient(
    account_url="https://<my_account_name>.blob.core.windows.net",
    credential=credential
)

DefaultAzureCredential'ı özelleştirme

Aşağıdaki bölümlerde, zincirden kimlik bilgilerini atmaya yönelik stratejiler açıklanmaktadır.

Tek bir kimlik bilgisini dışlama

Tek bir kimlik bilgisini DefaultAzureCredential'den dışlamak için, ön eki exclude olan anahtar sözcük parametresini kullanın. Örneğin:

credential = DefaultAzureCredential(
    exclude_environment_credential=True, 
    exclude_workload_identity_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

Yukarıdaki kod örneğinde EnvironmentCredential ve WorkloadIdentityCredential kimlik bilgisi zincirinden kaldırılır. Sonuç olarak, denenecek ilk kimlik bilgisi ManagedIdentityCredential olacaktır. Değiştirilen zincir şöyle görünür:

Oluşturucuda dışlama ön ekli anahtar sözcük parametreleri kullanılarak ortam kimlik bilgileri ve iş yükü kimlik bilgileri kaldırıldıktan sonra bir DefaultAzureCredential örneği için kimlik doğrulama akışını gösteren diyagram.

Not

InteractiveBrowserCredential varsayılan olarak dışlanır ve bu nedenle önceki diyagramda gösterilmez. InteractiveBrowserCredential eklemek için, exclude_interactive_browser_credential oluşturucusunu çağırdığınızda False anahtar sözcük parametresini DefaultAzureCredential olarak ayarlayın.

Daha fazla exclude ön ekli anahtar sözcük parametresi True olarak ayarlandıkça (kimlik bilgisi dışlamaları yapılandırılır), DefaultAzureCredential kullanmanın avantajları azalır. Böyle durumlarda, ChainedTokenCredential daha iyi bir seçimdir ve daha az kod gerektirir. Göstermek için, bu iki kod örneği aynı şekilde davranır:

credential = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_workload_identity_credential=True,
    exclude_shared_token_cache_credential=True,
    exclude_azure_powershell_credential=True,
    exclude_azure_developer_cli_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

Kimlik bilgisi türü kategorisini dışlama

Tüm Developer tool veya Deployed service kimlik bilgilerini dışlamak için ortam değişkenini AZURE_TOKEN_CREDENTIALSprod sırasıyla veya devolarak ayarlayın. değeri prod kullanıldığında, temel alınan kimlik bilgisi zinciri aşağıdaki gibi görünür:

AZURE_TOKEN_CREDENTIALS 'prod' olarak ayarlanmış DefaultAzureCredential öğesini gösteren diyagram.

değeri dev kullanıldığında, zincir aşağıdaki gibi görünür:

AZURE_TOKEN_CREDENTIALS 'dev' olarak ayarlanmış DefaultAzureCredential öğesini gösteren diyagram.

Önemli

Ortam AZURE_TOKEN_CREDENTIALS değişkeni 1.23.0 ve sonraki paket sürümlerinde desteklenir azure-identity .

ChainedTokenCredential'a genel bakış

ChainedTokenCredential , uygulamanızın gereksinimlerine uygun kimlik bilgileri eklediğiniz boş bir zincirdir. Örneğin:

credential = ChainedTokenCredential(
    AzureCliCredential(),
    AzureDeveloperCliCredential()
)

Yukarıdaki kod örneği, iki geliştirme zamanı kimlik bilgisi içeren uyarlanmış bir kimlik bilgisi zinciri oluşturur. AzureCliCredential önce denendi, ardından gerekirse AzureDeveloperCliCredential. Grafik biçiminde zincir şöyle görünür:

Azure CLI ve Azure Geliştirici CLI kimlik bilgilerinden oluşan ChainedTokenCredential örneğinin kimlik doğrulama akışını gösteren Diyagramı.

İpucu

İyileştirilmiş performans için ChainedTokenCredential kimlik bilgisi sıralamasını en az kullanılan kimlik bilgilerine kadar iyileştirin.

DefaultAzureCredential için kullanım kılavuzu

DefaultAzureCredential şüphesiz Azure Kimlik kitaplığını kullanmaya başlamanın en kolay yoludur, ancak bu kolaylıktan ödünler alınıyor. Uygulamanızı Azure'a dağıttığınızda uygulamanın kimlik doğrulama gereksinimlerini anlamanız gerekir. Bu nedenle, DefaultAzureCredentialTokenCredentialgibi belirli bir ManagedIdentityCredential uygulamasıyla değiştirin.

Bunun nedeni şu şekildedir:

  • Hata ayıklama zorlukları: Kimlik doğrulaması başarısız olduğunda, hata ayıklamak ve sorunlu kimlik bilgilerini belirlemek zor olabilir. Bir kimlik bilgisinden diğerine ilerleme durumunu ve her birinin başarı/başarısızlık durumunu görmek için günlüğe kaydetmeyi etkinleştirmeniz gerekir. Daha fazla bilgi için, Zincirlenmiş kimlik bilgilerinin hatalarını ayıklama bölümüne bakın.
  • Performans yükü: Birden çok kimlik bilgilerini sıralı olarak deneme işlemi performans ek yüküne neden olabilir. Örneğin, yerel bir geliştirme makinesinde çalışırken yönetilen kimlik kullanılamaz. Sonuç olarak, ManagedIdentityCredential ilgili excludeön ekli özelliği aracılığıyla açıkça devre dışı bırakılmadığı sürece yerel geliştirme ortamında her zaman başarısız olur.
  • Öngörülemeyen davranış: DefaultAzureCredential Belirli ortam değişkenlerinin varlığını denetler. Birinin konak makinede sistem düzeyinde bu ortam değişkenlerini eklemesi veya değiştirmesi mümkündür. Bu değişiklikler genel olarak uygulanır ve bu nedenle bu makinede çalışan herhangi bir uygulamadaki DefaultAzureCredential'in çalışma zamanı davranışını değiştirir.

Zincirlenmiş kimlik bilgisinde hata ayıklama

Beklenmeyen bir sorunu tanılamak veya zincirlenmiş kimlik bilgilerinin ne yaptığını anlamak için uygulamanızda günlüğe kaydetmeyi etkinleştirin. İsteğe bağlı olarak günlükleri yalnızca Azure Identity istemci kitaplığından yayılan olaylara göre filtreleyin. Örneğin:

import logging
from azure.identity import DefaultAzureCredential

# Set the logging level for the Azure Identity library
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Optional: Output logging levels to the console.
print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

Örnek teşkil etmesi için, parametresiz biçiminin DefaultAzureCredential kullanılarak bir blob depolama hesabına yapılan bir isteğin kimliğinin doğrulandığını varsayalım. Uygulama yerel geliştirme ortamında çalışır ve geliştirici Azure CLI kullanarak Azure'da kimlik doğrulaması yapar. Günlük kaydının logging.DEBUG olarak ayarlandığını varsayalım. Uygulama çalıştırıldığında, çıkışta aşağıdaki ilgili girdiler görüntülenir:

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
No environment configuration found.
ManagedIdentityCredential will use IMDS
EnvironmentCredential.get_token failed: EnvironmentCredential authentication unavailable. Environment variables are not fully configured.
Visit https://aka.ms/azsdk/python/identity/environmentcredential/troubleshoot to troubleshoot this issue.
ManagedIdentityCredential.get_token failed: ManagedIdentityCredential authentication unavailable, no response from the IMDS endpoint.     
SharedTokenCacheCredential.get_token failed: SharedTokenCacheCredential authentication unavailable. No accounts were found in the cache.
AzureCliCredential.get_token succeeded
[Authenticated account] Client ID: 00001111-aaaa-2222-bbbb-3333cccc4444. Tenant ID: aaaabbbb-0000-cccc-1111-dddd2222eeee. User Principal Name: unavailableUpn. Object ID (user): aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
DefaultAzureCredential acquired a token from AzureCliCredential

Yukarıdaki çıkışta şunların olduğuna dikkat edin:

  • EnvironmentCredential, ManagedIdentityCredentialve SharedTokenCacheCredential her bir microsoft Entra erişim belirtecini bu sırayla alamadı.
  • AzureCliCredential.get_token çağrısı başarılı olur ve çıkış, DefaultAzureCredential'den AzureCliCredential tarafından bir belirteç alındığını da gösterir. Başarıyla tamamlandığı için AzureCliCredential kullanıldıktan sonra başka kimlik bilgisi denenmedi.

Not

Yukarıdaki örnekte günlük düzeyi logging.DEBUG olarak ayarlanmıştır. Bu günlük düzeyini kullanırken dikkatli olun, çünkü hassas bilgileri çıkartabilir. Örneğin, bu örnekte istemci kimliği, kiracı kimliği ve geliştiricinin Azure'daki kullanıcı sorumlusunun nesne kimliği. Netlik için tüm geri izleme bilgileri çıktıdan kaldırıldı.