Python için Azure Identity istemci kitaplığı - sürüm 1.14.1

  • Makale

Azure Kimlik kitaplığı, Azure SDK genelinde Azure Active Directory (Azure AD) belirteç kimlik doğrulaması desteği sağlar. Azure AD belirteci kimlik doğrulamasını destekleyen Azure SDK istemcilerini oluşturmak için kullanılabilecek bir TokenCredential dizi uygulama sağlar.

Kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Azure AD belgeleri

Başlarken

Paketi yükleme

Pip ile Azure Identity'yi yükleyin:

pip install azure-identity

Önkoşullar

  • Azure aboneliği
  • Python 3.7 veya Python 3'ün son sürümü (bu kitaplık kullanım süresi sonu sürümlerini desteklemez)

Yerel geliştirme sırasında kimlik doğrulaması

Yerel olarak kodda hata ayıklama ve yürütme yaparken, geliştiricilerin Azure hizmetlerine yönelik çağrıların kimliğini doğrulamak için kendi hesaplarını kullanması normaldir. Azure Kimlik kitaplığı, yerel geliştirmeyi basitleştirmek için geliştirici araçları aracılığıyla kimlik doğrulamayı destekler.

Visual Studio Code aracılığıyla kimlik doğrulaması

Visual Studio Code kullanan geliştiriciler, düzenleyici aracılığıyla kimlik doğrulaması yapmak için Azure Hesabı uzantısını kullanabilir. veya VisualStudioCodeCredential kullanan DefaultAzureCredential uygulamalar, yerel olarak çalıştırılırken uygulamalarında çağrıların kimliğini doğrulamak için bu hesabı kullanabilir.

Visual Studio Code kimlik doğrulaması yapmak için Azure Hesabı uzantısının yüklü olduğundan emin olun. Yüklendikten sonra Komut Paleti'ni açın ve Azure: Oturum Aç komutunu çalıştırın.

Bu, 0.9.11'den yeni Azure Hesabı uzantısı sürümleriyle çalışmayan bilinen bir sorundurVisualStudioCodeCredential. Bu soruna uzun vadeli bir düzeltme devam ediyor. Bu arada , Azure CLI aracılığıyla kimlik doğrulamayı göz önünde bulundurun.

Azure CLI aracılığıyla kimlik doğrulaması

DefaultAzureCredential ve AzureCliCredentialkullanıcı Azure CLI'da oturum açtığında kimlik doğrulaması yapabilir. Azure CLI'da oturum açmak için komutunu çalıştırın az login. Varsayılan web tarayıcısına sahip bir sistemde, Azure CLI kullanıcının kimliğini doğrulamak için tarayıcıyı başlatır.

Varsayılan tarayıcı mevcut olmadığında cihaz az login kodu kimlik doğrulama akışını kullanır. Bu akış, çalıştırılarak az login --use-device-codeel ile de seçilebilir.

Azure Developer CLI aracılığıyla kimlik doğrulaması

IDE dışında kod kodlayan geliştiriciler kimlik doğrulaması için Azure Developer CLI de kullanabilir. veya AzureDeveloperCliCredential kullanan DefaultAzureCredential uygulamalar, yerel olarak çalıştırılırken uygulamalarında çağrıların kimliğini doğrulamak için bu hesabı kullanabilir.

kullanıcılar, Azure Developer CLI kimlik doğrulaması yapmak için komutunu azd auth loginçalıştırabilir. Varsayılan web tarayıcısına sahip bir sistemde çalışan kullanıcılar için, Azure Developer CLI kullanıcının kimliğini doğrulamak için tarayıcıyı başlatır.

Varsayılan web tarayıcısı olmayan sistemler için komut, azd auth login --use-device-code cihaz kodu kimlik doğrulama akışını kullanır.

Önemli kavramlar

Referans

Kimlik bilgisi, bir hizmet istemcisinin isteklerin kimliğini doğrulaması için gereken verileri içeren veya alabilen bir sınıftır. Azure SDK'sı genelindeki hizmet istemcileri, oluşturulduğunda bir kimlik bilgisi örneğini kabul eder ve isteklerin kimliğini doğrulamak için bu kimlik bilgilerini kullanır.

Azure Identity kitaplığı, Azure AD ile OAuth kimlik doğrulamasına odaklanır. bir Azure AD erişim belirteci alma yeteneğine sahip çeşitli kimlik bilgisi sınıfları sunar. Bu kitaplığın listesi için aşağıdaki Kimlik bilgisi sınıfları Kimlik bilgileri sınıfları bölümüne bakın.

DefaultAzureCredential

DefaultAzureCredential , yaygın üretim kimlik bilgilerini geliştirme kimlik bilgileriyle birleştirdiğinden Azure'da çalıştırılacak çoğu uygulama için uygundur. DefaultAzureCredential aşağıdaki mekanizmalar aracılığıyla kimlik doğrulama girişiminde bulunur ve başarılı olduğunda bu sırayla durduruluyor:

Not: DefaultAzureCredential makul varsayılan davranışlarla yaygın senaryoları işleyerek kitaplığı kullanmaya başlamayı basitleştirmeye yöneliktir. Daha fazla denetim isteyen veya senaryosu varsayılan ayarlar tarafından sunulmayan geliştiriciler diğer kimlik bilgileri türlerini kullanmalıdır.

DefaultAzureCredential authentication flow

  1. Ortam - DefaultAzureCredential ortam aracılığıyla belirtilen hesap bilgilerini okur ve kimlik doğrulaması için kullanır.
  2. İş Yükü Kimliği - Uygulama Yönetilen Kimlik etkinken Azure Kubernetes Service dağıtılırsa, DefaultAzureCredential uygulamayla kimlik doğrulaması yapılır.
  3. Yönetilen Kimlik - Uygulama, Yönetilen Kimlik etkinleştirilmiş bir Azure konağına dağıtılırsa, DefaultAzureCredential uygulamayla kimlik doğrulaması yapar.
  4. Azure CLI - Bir kullanıcı Azure CLI az login komutuyla oturum açtıysa, DefaultAzureCredential o kullanıcı olarak kimlik doğrulaması yapar.
  5. Azure PowerShell - Bir kullanıcı Azure PowerShell Connect-AzAccount komutuyla oturum açtıysa, DefaultAzureCredential o kullanıcı olarak kimlik doğrulaması yapar.
  6. Azure Developer CLI - Geliştiricinin kimliği Azure Developer CLI azd auth login komutuyla doğrulandıysa, DefaultAzureCredential bu hesapla kimlik doğrulaması yapılır.
  7. Etkileşimli tarayıcı - Etkinleştirilirse, DefaultAzureCredential kullanıcının kimliğini varsayılan tarayıcı aracılığıyla etkileşimli olarak doğrular. Bu kimlik bilgisi türü varsayılan olarak devre dışıdır.

Hakkında not VisualStudioCodeCredential

Bilinen bir sorunVisualStudioCodeCredential nedeniyle belirteç zincirinden DefaultAzureCredential kaldırıldı. Sorun gelecek bir sürümde çözüldüğünde, bu değişiklik geri döndürülür.

Örnekler

Aşağıdaki örnekler aşağıda verilmiştir:

Ile kimlik doğrulaması DefaultAzureCredential

ortamınızı kullanacak DefaultAzureCredential şekilde yapılandırma hakkında daha fazla ayrıntı sınıfının başvuru belgelerinde bulunabilir.

Bu örnekte kullanarak DefaultAzureCredentialazure-storage-blob kitaplığından kimlik doğrulaması BlobServiceClient gösterilmektedir.

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

ile etkileşimli kimlik doğrulamasını etkinleştirme DefaultAzureCredential

Etkileşimli kimlik doğrulaması varsayılan olarak içinde DefaultAzureCredential devre dışıdır ve bir anahtar sözcük bağımsız değişkeniyle etkinleştirilebilir:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Etkinleştirildiğinde, DefaultAzureCredential başka bir kimlik bilgisi olmadığında sistemin varsayılan web tarayıcısı aracılığıyla etkileşimli kimlik doğrulamasına geri döner.

için kullanıcı tarafından atanan yönetilen kimlik belirtme DefaultAzureCredential

Birçok Azure ana bilgisayar, kullanıcı tarafından atanan yönetilen kimliğin atanmasına izin verir. Kullanıcı tarafından atanan kimliğin kimliğini doğrulamak üzere yapılandırmak DefaultAzureCredential için anahtar sözcük bağımsız değişkenini managed_identity_client_id kullanın:

DefaultAzureCredential(managed_identity_client_id=client_id)

Alternatif olarak ortam değişkenini AZURE_CLIENT_ID kimliğin istemci kimliğine ayarlayın.

ile özel kimlik doğrulama akışı tanımlama ChainedTokenCredential

DefaultAzureCredential Genellikle Azure için uygulama geliştirmeye başlamanın en hızlı yoludur. Daha gelişmiş senaryolar için ChainedTokenCredential , kimlik doğrulaması sırasında sıralı olarak denenecek birden çok kimlik bilgisi örneğini bağlar. Bir belirteç sağlayana veya bir hata nedeniyle kimlik doğrulaması başarısız olana kadar zincirlenmiş kimlik bilgilerini sırayla dener.

Aşağıdaki örnek, önce yönetilen kimlik kullanarak kimlik doğrulamayı deneyecek bir kimlik bilgisi oluşturmayı gösterir. Yönetilen kimlik kullanılamadığında kimlik bilgileri Azure CLI aracılığıyla kimlik doğrulamasına geri döner. Bu örnek, azure-eventhub istemci kitaplığından öğesini kullanırEventHubProducerClient.

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)

Zaman uyumsuz kimlik bilgileri

Bu kitaplık bir zaman uyumsuz API kümesi içerir. azure.identity.aio dosyasında zaman uyumsuz kimlik bilgilerini kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Daha fazla bilgi için bkz. azure-core belgeleri.

Zaman uyumsuz kimlik bilgileri artık gerekli olmadığında kapatılmalıdır. Her zaman uyumsuz kimlik bilgisi bir zaman uyumsuz bağlam yöneticisidir ve zaman uyumsuz close bir yöntem tanımlar. Örnek:

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

Bu örnekte, zaman uyumsuz SecretClient kimlik bilgileriyle azure-keyvault-secrets'dan zaman uyumsuz kimlik doğrulaması gösterilmektedir.

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)

Yönetilen kimlik desteği

Yönetilen kimlik kimlik doğrulaması, aşağıdaki Azure hizmetleri için doğrudan veya ManagedIdentityCredential aracılığıyla DefaultAzureCredential desteklenir:

Örnekler

Kullanıcı tarafından atanan yönetilen kimlikle kimlik doğrulaması

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)

Sistem tarafından atanan yönetilen kimlikle kimlik doğrulaması

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

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

Bulut yapılandırması

Kimlik bilgileri varsayılan olarak Azure Genel Bulut için Azure AD uç noktasında kimlik doğrulaması yapılır. Azure Kamu veya özel bulut gibi diğer bulutlardaki kaynaklara erişmek için kimlik bilgilerini bağımsız değişkeniyle authority yapılandırın. AzureAuthorityHosts , iyi bilinen bulutlar için yetkilileri tanımlar:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Bulutunuzun yetkilisi içinde AzureAuthorityHostslistelenmiyorsa, url'sini açıkça belirtebilirsiniz:

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

Bağımsız değişkeni belirtmeye authority alternatif olarak ortam değişkenini AZURE_AUTHORITY_HOST bulutunuzun yetkilisinin URL'sine de ayarlayabilirsiniz. Bu yaklaşım, aynı bulutta kimlik doğrulaması yapmak için birden çok kimlik bilgisi yapılandırırken yararlıdır:

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

Tüm kimlik bilgileri bu yapılandırmayı gerektirmez. gibi AzureCliCredentialbir geliştirme aracı aracılığıyla kimlik doğrulaması yapılan kimlik bilgileri, bu aracın yapılandırmasını kullanır. Benzer şekilde, VisualStudioCodeCredential bir authority bağımsız değişken kabul eder ancak varsayılan olarak VS Code'un "Azure: Bulut" ayarıyla eşleşen yetkiliyi kullanır.

Kimlik bilgisi sınıfları

Azure'da barındırılan uygulamaların kimliğini doğrulama

Kimlik Bilgisi Kullanım
DefaultAzureCredential Azure'da çalıştırılan uygulamaları hızla geliştirmeye başlamak için basitleştirilmiş bir kimlik doğrulama deneyimi sağlar.
ChainedTokenCredential Kullanıcıların birden çok kimlik bilgisi oluşturan özel kimlik doğrulama akışları tanımlamasına olanak tanır.
EnvironmentCredential Ortam değişkenlerinde belirtilen kimlik bilgileri aracılığıyla bir hizmet sorumlusu veya kullanıcının kimliğini doğrular.
ManagedIdentityCredential Bir Azure kaynağının yönetilen kimliğinin kimliğini doğrular.
WorkloadIdentityCredential Kubernetes'te Azure AD iş yükü kimliğini destekler.

Hizmet sorumlularının kimliğini doğrulama

Kimlik Bilgisi Kullanım Başvuru
CertificateCredential Sertifika kullanarak hizmet sorumlusu kimliğini doğrular. Hizmet sorumlusu kimlik doğrulaması
ClientAssertionCredential İmzalı istemci onayı kullanarak hizmet sorumlusu kimliğini doğrular.
ClientSecretCredential Gizli dizi kullanarak hizmet sorumlusu kimliğini doğrular. Hizmet sorumlusu kimlik doğrulaması

Kullanıcıların kimliklerini doğrulama

Kimlik Bilgisi Kullanım Başvuru
AuthorizationCodeCredential Daha önce alınan yetkilendirme koduyla kullanıcının kimliğini doğrular. OAuth2 kimlik doğrulama kodu
DeviceCodeCredential Kullanıcı arabirimi sınırlı cihazlarda kullanıcının kimliğini etkileşimli olarak doğrular. Cihaz kodu kimlik doğrulaması
InteractiveBrowserCredential Kullanıcının kimliğini varsayılan sistem tarayıcısıyla etkileşimli olarak doğrular. OAuth2 kimlik doğrulama kodu
OnBehalfOfCredential Temsilci olarak atanan kullanıcı kimliğini ve izinlerini istek zinciri aracılığıyla yayılım. Adına kimlik doğrulaması
UsernamePasswordCredential Kullanıcı adı ve parola ile kullanıcının kimliğini doğrular (çok faktörlü kimlik doğrulamasını desteklemez). Kullanıcı adı + parola kimlik doğrulaması

Geliştirme araçlarıyla kimlik doğrulaması

Kimlik Bilgisi Kullanım Başvuru
AzureCliCredential Azure CLI ile geliştirme ortamında kimlik doğrulaması yapar. Azure CLI kimlik doğrulaması
AzureDeveloperCliCredential Azure Developer CLI ile geliştirme ortamında kimlik doğrulaması yapar. Azure Developer CLI Başvurusu
AzurePowerShellCredential Azure PowerShell ile geliştirme ortamında kimlik doğrulaması yapar. kimlik doğrulaması Azure PowerShell
VisualStudioCodeCredential Kullanıcı Visual Studio Code Azure Hesabı uzantısında oturum açtığında kimlik doğrulaması yapar. VS Code Azure Hesabı uzantısı

Ortam değişkenleri

DefaultAzureCredential ve EnvironmentCredential ortam değişkenleriyle yapılandırılabilir. Her kimlik doğrulama türü belirli değişkenler için değerler gerektirir:

Gizli dizili hizmet sorumlusu

Değişken adı Değer
AZURE_CLIENT_ID Azure AD uygulamasının kimliği
AZURE_TENANT_ID Uygulamanın Azure AD kiracısının kimliği
AZURE_CLIENT_SECRET uygulamanın istemci gizli dizilerinden biri

Sertifikalı hizmet sorumlusu

Değişken adı Değer
AZURE_CLIENT_ID Azure AD uygulamasının kimliği
AZURE_TENANT_ID Uygulamanın Azure AD kiracısının kimliği
AZURE_CLIENT_CERTIFICATE_PATH pem veya PKCS12 sertifika dosyasının yolu ( özel anahtar da dahil)
AZURE_CLIENT_CERTIFICATE_PASSWORD varsa sertifika dosyasının parolası

Kullanıcı adı ve parola

Değişken adı Değer
AZURE_CLIENT_ID Azure AD uygulamasının kimliği
AZURE_USERNAME kullanıcı adı (genellikle e-posta adresi)
AZURE_PASSWORD bu kullanıcının parolası

Yapılandırma yukarıdaki sırayla denendi. Örneğin, bir istemci gizli dizisi ve sertifikanın değerleri varsa, istemci gizli dizisi kullanılır.

Belirteç önbelleğe alma

Belirteç önbelleğe alma, Azure Kimlik kitaplığı tarafından sağlanan ve uygulamaların şunları yapmasına olanak tanıyan bir özelliktir:

  • Bellekteki (varsayılan) veya diskteki (kabul etme) önbellek belirteçleri.
  • Dayanıklılığı ve performansı geliştirin.
  • Erişim belirteçlerini almak için Azure AD yapılan istek sayısını azaltın.

Azure Kimlik kitaplığı hem bellek içi hem de kalıcı disk önbelleği sunar. Diğer ayrıntılar için belirteç önbelleğe alma belgelerine bakın.

Sorun giderme

Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için sorun giderme kılavuzuna bakın.

Hata işleme

Kimlik bilgileri, gerekli veri veya durum eksik olduğundan kimlik doğrulamayı deneyemediklerinde ortaya çıkar CredentialUnavailableError . Örneğin, EnvironmentCredential tamamlanmamış olduğunda bu özel durumu tetikler.

Kimlik bilgileri kimlik doğrulaması başarısız olduğunda ortaya çıkar azure.core.exceptions.ClientAuthenticationError . ClientAuthenticationError , kimlik doğrulamasının neden başarısız olduğunu açıklayan bir message özniteliğine sahiptir. veya ChainedTokenCredentialtarafından DefaultAzureCredential tetiklendiğinde, ileti zincirdeki her kimlik bilgisinden hata iletileri toplar.

Belirli Azure AD hatalarını işleme hakkında daha fazla bilgi için Azure AD hata kodu belgelerine bakın.

Günlüğe Kaydetme

Bu kitaplık, günlüğe kaydetme için standart günlük kitaplığını kullanır. Kimlik bilgileri, INFO düzeyinde HTTP oturumları (URL'ler, üst bilgiler vb.) dahil olmak üzere temel bilgileri günlüğe kaydeder. Bu günlük girdileri kimlik doğrulama gizli dizileri içermez.

İstek/yanıt gövdeleri ve üst bilgi değerleri de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü varsayılan olarak etkin değildir. Bağımsız değişkenle logging_enable etkinleştirilebilir. Örnek:

credential = DefaultAzureCredential(logging_enable=True)

DİkKAT: Kimlik bilgilerinden hata ayıklama düzeyi günlükleri hassas bilgiler içerir. Hesap güvenliğinin tehlikeye atılmasını önlemek için bu günlüklerin korunması gerekir.

Sonraki adımlar

İstemci kitaplığı desteği

Azure SDK yayın sayfasında listelenen ve Azure AD kimlik doğrulamasını destekleyen istemci ve yönetim kitaplıkları bu kitaplıktan kimlik bilgilerini kabul eder. Bu kitaplıkları kullanma hakkında daha fazla bilgiyi yayın sayfasından bağlanan belgelerinde bulabilirsiniz.

Bilinen sorunlar

Bu kitaplık B2C Azure AD desteklemez.

Diğer açık sorunlar için kitaplığın GitHub deposuna bakın.

Geribildirim gönderme

Hatalarla karşılaşırsanız veya önerileriniz varsa bir sorun açın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bunu CLA'mızı kullanarak tüm depolarda yalnızca bir kez yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları hakkında SSS bölümüne bakın veya başka soru ya da görüşleriniz olursa opencode@microsoft.com ile iletişime geçin.

İzlenimler