Pustaka klien Azure Identity untuk Python - versi 1.14.1

Pustaka Azure Identity menyediakan dukungan autentikasi token Azure Active Directory (Azure AD) di seluruh Azure SDK. Ini menyediakan serangkaian TokenCredential implementasi, yang dapat digunakan untuk membangun klien Azure SDK yang mendukung autentikasi token Azure AD.

Kode sumber | Paket (PyPI) | Paket (Conda) | Dokumentasi | referensi APIdokumentasi Azure AD

Memulai

Menginstal paket

Instal Azure Identity dengan pip:

pip install azure-identity

Prasyarat

• Langganan Azure
• Python 3.7 atau versi terbaru Python 3 (pustaka ini tidak mendukung versi akhir masa pakai)

Mengautentikasi selama pengembangan lokal

Saat men-debug dan mengeksekusi kode secara lokal, biasanya pengembang menggunakan akun mereka sendiri untuk mengautentikasi panggilan ke layanan Azure. Pustaka Azure Identity mendukung autentikasi melalui alat pengembang untuk menyederhanakan pengembangan lokal.

Mengautentikasi melalui Visual Studio Code

Pengembang yang menggunakan Visual Studio Code dapat menggunakan ekstensi Akun Azure untuk mengautentikasi melalui editor. Aplikasi yang menggunakan DefaultAzureCredential atau VisualStudioCodeCredential kemudian dapat menggunakan akun ini untuk mengautentikasi panggilan di aplikasi mereka saat berjalan secara lokal.

Untuk mengautentikasi di Visual Studio Code, pastikan ekstensi Akun Azure diinstal. Setelah diinstal, buka Palet Perintah dan jalankan perintah Azure: Masuk .

Ini adalah masalah umum yang VisualStudioCodeCredential tidak berfungsi dengan versi ekstensi Akun Azure yang lebih baru dari 0.9.11. Perbaikan jangka panjang untuk masalah ini sedang berlangsung. Sementara itu, pertimbangkan untuk mengautentikasi melalui Azure CLI.

Mengautentikasi melalui Azure CLI

DefaultAzureCredential dan AzureCliCredential dapat mengautentikasi saat pengguna masuk ke Azure CLI. Untuk masuk ke Azure CLI, jalankan az login. Pada sistem dengan browser web default, Azure CLI akan meluncurkan browser untuk mengautentikasi pengguna.

Ketika tidak ada browser default yang tersedia, az login akan menggunakan alur autentikasi kode perangkat. Alur ini juga dapat dipilih secara manual dengan menjalankan az login --use-device-code.

Mengautentikasi melalui Azure Developer CLI

Pengkodian pengembang di luar IDE juga dapat menggunakan Azure Developer CLI untuk mengautentikasi. Aplikasi yang menggunakan DefaultAzureCredential atau AzureDeveloperCliCredential kemudian dapat menggunakan akun ini untuk mengautentikasi panggilan dalam aplikasinya saat berjalan secara lokal.

Untuk mengautentikasi dengan Azure Developer CLI, pengguna dapat menjalankan perintah azd auth login. Untuk pengguna yang berjalan pada sistem dengan browser web default, Azure Developer CLI akan meluncurkan browser untuk mengautentikasi pengguna.

Untuk sistem tanpa browser web bawaan, perintah azd auth login --use-device-code akan menggunakan alur autentikasi kode perangkat.

Konsep utama

Kredensial

Kredensial adalah kelas yang berisi atau dapat memperoleh data yang diperlukan untuk klien layanan untuk mengautentikasi permintaan. Klien layanan di seluruh Azure SDK menerima instans kredensial saat dibuat, dan menggunakan kredensial tersebut untuk mengautentikasi permintaan.

Pustaka Azure Identity berfokus pada autentikasi OAuth dengan Azure AD. Ini menawarkan berbagai kelas kredensial yang mampu memperoleh token akses Azure AD. Lihat bagian Kelas info kredensial di bawah ini untuk daftar kelas kredensial pustaka ini.

DefaultAzureCredential

DefaultAzureCredential sesuai untuk sebagian besar aplikasi yang akan berjalan di Azure karena menggabungkan kredensial produksi umum dengan kredensial pengembangan. DefaultAzureCredential mencoba untuk mengautentikasi melalui mekanisme berikut, dalam urutan ini, berhenti ketika berhasil:

Catatan: DefaultAzureCredential dimaksudkan untuk menyederhanakan memulai pustaka dengan menangani skenario umum dengan perilaku default yang wajar. Pengembang yang menginginkan lebih banyak kontrol atau skenarionya tidak dilayani oleh pengaturan default harus menggunakan jenis kredensial lainnya.

1. Lingkungan - DefaultAzureCredential akan membaca informasi akun yang ditentukan melalui variabel lingkungan dan menggunakannya untuk mengautentikasi.
2. Identitas Beban Kerja - Jika aplikasi disebarkan ke Azure Kubernetes Service dengan Identitas Terkelola diaktifkan, DefaultAzureCredential akan mengautentikasi dengannya.
3. Identitas Terkelola - Jika aplikasi disebarkan ke host Azure dengan Identitas Terkelola diaktifkan, DefaultAzureCredential akan mengautentikasi dengannya.
4. Azure CLI - Jika pengguna telah masuk melalui perintah Azure CLI az login , DefaultAzureCredential akan mengautentikasi sebagai pengguna tersebut.
5. Azure PowerShell - Jika pengguna telah masuk melalui perintah Azure PowerShellConnect-AzAccount, DefaultAzureCredential akan mengautentikasi sebagai pengguna tersebut.
6. Azure Developer CLI - Jika pengembang telah mengautentikasi melalui perintah Azure Developer CLIazd auth login, akan mengautentikasi dengan akun tersebutDefaultAzureCredential.
7. Browser interaktif - Jika diaktifkan, DefaultAzureCredential akan secara interaktif mengautentikasi pengguna melalui browser default. Tipe kredensial ini dinonaktifkan secara default.

Catatan tentang VisualStudioCodeCredential

Karena masalah yang diketahui, VisualStudioCodeCredential telah dihapus dari DefaultAzureCredential rantai token. Ketika masalah diselesaikan dalam rilis mendatang, perubahan ini akan dikembalikan.

Contoh

Contoh berikut disediakan di bawah ini:

• Mengautentikasi dengan DefaultAzureCredential
• Menentukan alur autentikasi kustom dengan ChainedTokenCredential
• Kredensial asinkron

Mengautentikasi dengan DefaultAzureCredential

Detail selengkapnya tentang mengonfigurasi lingkungan Anda untuk menggunakan DefaultAzureCredential dapat ditemukan dalam dokumentasi referensi kelas.

Contoh ini menunjukkan autentikasi BlobServiceClient dari pustaka azure-storage-blob menggunakan DefaultAzureCredential.

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Mengaktifkan autentikasi interaktif dengan DefaultAzureCredential

Autentikasi interaktif dinonaktifkan secara DefaultAzureCredential default dan dapat diaktifkan dengan argumen kata kunci:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Saat diaktifkan, DefaultAzureCredential kembali ke autentikasi interaktif melalui browser web default sistem ketika tidak ada kredensial lain yang tersedia.

Tentukan identitas terkelola yang ditetapkan pengguna untuk DefaultAzureCredential

Banyak host Azure memungkinkan penetapan identitas terkelola yang ditetapkan pengguna. Untuk mengonfigurasi DefaultAzureCredential untuk mengautentikasi identitas yang ditetapkan pengguna, gunakan managed_identity_client_id argumen kata kunci:

DefaultAzureCredential(managed_identity_client_id=client_id)

Atau, atur variabel AZURE_CLIENT_ID lingkungan ke ID klien identitas.

Menentukan alur autentikasi kustom dengan ChainedTokenCredential

DefaultAzureCredential umumnya adalah cara tercepat untuk mulai mengembangkan aplikasi untuk Azure. Untuk skenario yang lebih canggih, ChainedTokenCredential menautkan beberapa instans kredensial untuk dicoba secara berurutan saat mengautentikasi. Ini akan mencoba setiap kredensial berantai pada gilirannya sampai salah satu menyediakan token atau gagal mengautentikasi karena kesalahan.

Contoh berikut menunjukkan pembuatan kredensial yang akan terlebih dahulu mencoba mengautentikasi menggunakan identitas terkelola. Kredensial akan kembali ke autentikasi melalui Azure CLI saat identitas terkelola tidak tersedia. Contoh ini menggunakan EventHubProducerClient dari pustaka klien 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)

Kredensial asinkron

Pustaka ini mencakup sekumpulan API asinkron. Untuk menggunakan kredensial asinkron di azure.identity.aio, Anda harus terlebih dahulu menginstal transportasi asinkron, seperti aiohttp. Untuk informasi selengkapnya, lihat dokumentasi azure-core.

Kredensial asinkron harus ditutup ketika tidak lagi diperlukan. Setiap kredensial asinkron adalah manajer konteks asinkron dan mendefinisikan metode asinkron close . Contohnya:

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

Contoh ini menunjukkan autentikasi asinkron SecretClient dari azure-keyvault-secrets dengan kredensial asinkron.

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)

Dukungan identitas terkelola

Autentikasi identitas terkelola didukung melalui DefaultAzureCredential atau ManagedIdentityCredential secara langsung untuk layanan Azure berikut:

• Azure App Service dan Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Struktur Layanan Azure
• Komputer Virtual Azure
• Set Skala Azure Virtual Machines

Contoh

Mengautentikasi dengan identitas terkelola yang ditetapkan pengguna

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)

Mengautentikasi dengan identitas terkelola yang ditetapkan sistem

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

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

Konfigurasi awan

Kredensial default untuk mengautentikasi ke titik akhir Azure AD untuk Azure Public Cloud. Untuk mengakses sumber daya di cloud lain, seperti Azure Government atau cloud privat, konfigurasikan kredensial dengan authority argumen . AzureAuthorityHosts mendefinisikan otoritas untuk cloud terkenal:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Jika otoritas untuk cloud Anda tidak tercantum di AzureAuthorityHosts, Anda dapat secara eksplisit menentukan URL-nya:

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

Sebagai alternatif untuk menentukan authority argumen, Anda juga dapat mengatur AZURE_AUTHORITY_HOST variabel lingkungan ke URL otoritas cloud Anda. Pendekatan ini berguna saat mengonfigurasi beberapa kredensial untuk mengautentikasi ke cloud yang sama:

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

Tidak semua kredensial memerlukan konfigurasi ini. Kredensial yang mengautentikasi melalui alat pengembangan, seperti AzureCliCredential, gunakan konfigurasi alat tersebut. Demikian pula, VisualStudioCodeCredential menerima authority argumen tetapi default ke otoritas yang cocok dengan pengaturan "Azure: Cloud" Visual Studio Code.

Kelas kredensial

Mengautentikasi aplikasi yang dihosting Azure

Kredensial	Penggunaan
DefaultAzureCredential	Memberikan pengalaman autentikasi yang disederhanakan untuk mulai mengembangkan aplikasi dengan cepat yang berjalan di Azure.
ChainedTokenCredential	Memungkinkan pengguna menentukan alur autentikasi kustom yang menyusun beberapa kredensial.
EnvironmentCredential	Mengautentikasi perwakilan layanan atau pengguna melalui informasi kredensial yang ditentukan dalam variabel lingkungan.
ManagedIdentityCredential	Mengautentikasi identitas terkelola dari sumber daya Azure.
WorkloadIdentityCredential	Mendukung identitas beban kerja Azure AD di Kubernetes.

Mengautentikasi perwakilan layanan

Kredensial	Penggunaan	Referensi
CertificateCredential	Mengautentikasi perwakilan layanan menggunakan sertifikat.	Autentikasi perwakilan layanan
ClientAssertionCredential	Mengautentikasi perwakilan layanan menggunakan pernyataan klien yang ditandatangani.
ClientSecretCredential	Mengautentikasi perwakilan layanan menggunakan rahasia.	Autentikasi perwakilan layanan

Autentikasi pengguna

Kredensial	Penggunaan	Referensi
AuthorizationCodeCredential	Mengautentikasi pengguna dengan kode otorisasi yang diperoleh sebelumnya.	Kode autentikasi OAuth2
DeviceCodeCredential	Mengautentikasi pengguna secara interaktif pada perangkat dengan antarmuka pengguna yang terbatas.	Autentikasi kode perangkat
InteractiveBrowserCredential	Mengautentikasi pengguna secara interaktif dengan browser sistem default.	Kode autentikasi OAuth2
OnBehalfOfCredential	Menyebarkan identitas dan izin pengguna yang didelegasikan melalui rantai permintaan.	Atas nama autentikasi
UsernamePasswordCredential	Mengautentikasi pengguna dengan nama pengguna dan kata sandi (tidak mendukung autentikasi multifaktor).	Autentikasi nama pengguna + kata sandi

Mengautentikasi melalui alat pengembangan

Kredensial	Penggunaan	Referensi
AzureCliCredential	Mengautentikasi di lingkungan pengembangan dengan Azure CLI.	Autentikasi Azure CLI
AzureDeveloperCliCredential	Mengautentikasi di lingkungan pengembangan dengan Azure Developer CLI.	Referensi Azure Developer CLI
AzurePowerShellCredential	Mengautentikasi di lingkungan pengembangan dengan Azure PowerShell.	autentikasi Azure PowerShell
VisualStudioCodeCredential	Mengautentikasi saat pengguna masuk ke ekstensi Akun Azure Visual Studio Code.	Ekstensi Akun Azure Visual Studio Code

Variabel lingkungan

DefaultAzureCredential dan EnvironmentCredential dapat dikonfigurasi dengan variabel lingkungan. Setiap jenis autentikasi memerlukan nilai untuk variabel tertentu:

Perwakilan layanan dengan rahasia

Nama variabel	Nilai
AZURE_CLIENT_ID	ID aplikasi Azure AD
AZURE_TENANT_ID	ID penyewa Azure AD aplikasi
AZURE_CLIENT_SECRET	salah satu rahasia klien aplikasi

Perwakilan layanan dengan sertifikat

Nama variabel	Nilai
AZURE_CLIENT_ID	ID aplikasi Azure AD
AZURE_TENANT_ID	ID penyewa Azure AD aplikasi
AZURE_CLIENT_CERTIFICATE_PATH	jalur ke file sertifikat PEM atau PKCS12 termasuk kunci privat
AZURE_CLIENT_CERTIFICATE_PASSWORD	kata sandi file sertifikat, jika ada

Nama pengguna dan kata sandi

Nama variabel	Nilai
AZURE_CLIENT_ID	ID aplikasi Azure AD
AZURE_USERNAME	nama pengguna (biasanya alamat email)
AZURE_PASSWORD	kata sandi pengguna tersebut

Konfigurasi dicoba dengan urutan di atas. Misalnya, jika nilai untuk baik rahasia klien dan sertifikat ada, rahasia klien digunakan.

Penembolokan token

Penembolokan token adalah fitur yang disediakan oleh pustaka Azure Identity yang memungkinkan aplikasi untuk:

• Token cache dalam memori (default) atau pada disk (keikutsertaan).
• Meningkatkan ketahanan dan performa.
• Kurangi jumlah permintaan yang dibuat ke Azure AD untuk mendapatkan token akses.

Pustaka Azure Identity menawarkan penembolokan disk dalam memori dan persisten. Untuk detail selengkapnya, lihat dokumentasi penembolokan token.

Pemecahan Masalah

Lihat panduan pemecahan masalah untuk detail tentang cara mendiagnosis berbagai skenario kegagalan.

Penanganan kesalahan

Kredensial muncul CredentialUnavailableError saat tidak dapat mencoba autentikasi karena tidak memiliki data atau status yang diperlukan. Misalnya, EnvironmentCredential akan meningkatkan pengecualian ini ketika tidak lengkap.

Kredensial memunculkan azure.core.exceptions.ClientAuthenticationError saat gagal diautentikasi. ClientAuthenticationError memiliki message atribut , yang menjelaskan mengapa autentikasi gagal. Saat dimunculkan oleh DefaultAzureCredential atau ChainedTokenCredential, pesan mengumpulkan pesan kesalahan dari setiap kredensial dalam rantai.

Untuk informasi selengkapnya tentang menangani kesalahan Azure AD tertentu, lihat dokumentasi kode kesalahan Azure AD.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar log kredensial, termasuk sesi HTTP (URL, header, dll.) di tingkat INFO. Entri log ini tidak berisi rahasia autentikasi.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan nilai header, tidak diaktifkan secara default. Ini dapat diaktifkan dengan logging_enable argumen . Contohnya:

credential = DefaultAzureCredential(logging_enable=True)

PERHATIAN: Log tingkat DEBUG dari kredensial berisi informasi sensitif. Log ini harus dilindungi untuk menghindari mengorbankan keamanan akun.

Langkah berikutnya

Dukungan pustaka klien

Pustaka klien dan manajemen tercantum di halaman rilis Azure SDK yang mendukung autentikasi Azure AD menerima kredensial dari pustaka ini. Anda dapat mempelajari selengkapnya tentang menggunakan pustaka ini dalam dokumentasinya, yang ditautkan dari halaman rilis.

Masalah yang diketahui

Pustaka ini tidak mendukung Azure AD B2C.

Untuk masalah terbuka lainnya, lihat repositori GitHub pustaka.

Berikan umpan balik

Jika Anda menemukan bug atau memiliki saran, buka masalah.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repositori menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat FAQ Kode Etik atau hubungi opencode@microsoft.com untuk mengajukan pertanyaan atau komentar tambahan.