Bagikan melalui

Rantai kredensial di pustaka Azure Identity untuk Python

Pustaka Azure Identity menyediakan kredensial —kelas publik yang mengimplementasikan protokol TokenCredential pustaka Azure Core yang. Kredensial mewakili alur autentikasi yang berbeda untuk memperoleh token akses dari ID Microsoft Entra. Kredensial ini dapat ditautkan bersama untuk membentuk urutan mekanisme autentikasi untuk dicoba.

Cara kerja kredensial berantai

Pada runtime, rantai kredensial mencoba melakukan otentikasi menggunakan kredensial pertama dalam urutan. Jika kredensial tersebut gagal memperoleh token akses, kredensial berikutnya dalam urutan dicoba, dan sebagainya, hingga token akses berhasil diperoleh. Diagram urutan berikut mengilustrasikan perilaku ini:

Diagram yang memperlihatkan urutan rantai kredensial.

Mengapa menggunakan rantai kredensial

Kredensial berantai dapat memberikan manfaat sebagai berikut:

  • Kesadaran lingkungan: Secara otomatis memilih kredensial yang paling tepat berdasarkan lingkungan tempat aplikasi berjalan. Tanpa itu, Anda harus menulis kode seperti ini:

    # 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()

  • Transisi tanpa hambatan: Aplikasi Anda dapat berpindah dari pengembangan lokal ke lingkungan penahapan atau produksi Anda tanpa mengubah kode autentikasi.

  • Peningkatan ketahanan: Menyertakan mekanisme fallback yang berpindah ke kredensial berikutnya ketika sebelumnya gagal memperoleh token akses.

Cara memilih kredensial berantai

Ada dua filosofi yang berbeda dengan rantai kredensial:

  • "Hancurkan" rantai: Mulailah dengan rantai yang telah dikonfigurasi sebelumnya dan kecualikan apa yang tidak Anda butuhkan. Untuk pendekatan ini, lihat bagian DefaultAzureCredential Gambaran Umum.
  • "Bangun" rantai: Mulailah dengan rantai kosong dan sertakan hanya apa yang Anda butuhkan. Untuk pendekatan ini, lihat bagian Ringkasan ChainedTokenCredential.

Gambaran umum DefaultAzureCredential

DefaultAzureCredential adalah rantai kredensial yang telah dikonfigurasikan sebelumnya. Ini dirancang untuk mendukung banyak lingkungan, bersama dengan alur autentikasi dan alat pengembang yang paling umum. Dalam bentuk grafis, rantai yang mendasar terlihat seperti ini:

Diagram yang memperlihatkan alur autentikasi DefaultAzureCredential.

Urutan di mana DefaultAzureCredential melakukan upaya kredensial adalah sebagai berikut.

Pesanan Kredensial Deskripsi Aktifkan secara default?
1 Lingkungan Membaca kumpulan variabel lingkungan untuk menentukan apakah perwakilan layanan aplikasi (pengguna aplikasi) dikonfigurasi untuk aplikasi. Jika demikian, DefaultAzureCredential gunakan nilai-nilai ini untuk mengautentikasi aplikasi ke Azure. Metode ini paling sering digunakan di lingkungan server tetapi juga dapat digunakan saat mengembangkan secara lokal. Ya
2 Identitas Beban Kerja Jika aplikasi disebarkan ke host Azure dengan Identitas Beban Kerja diaktifkan, autentikasi akun tersebut. Ya
3 Identitas Terkelola Jika aplikasi disebarkan ke host Azure dengan Identitas Terkelola diaktifkan, autentikasi aplikasi ke Azure menggunakan Identitas Terkelola tersebut. Ya
4 Cache Token Bersama Hanya di Windows, jika pengembang mengautentikasi ke Azure dengan masuk ke Visual Studio, autentikasi aplikasi ke Azure menggunakan akun yang sama. Ya
5 Azure CLI Jika pengembang mengautentikasi ke Azure menggunakan perintah Azure CLI az login , autentikasi aplikasi ke Azure menggunakan akun yang sama. Ya
6 Azure PowerShell Jika pengembang mengautentikasi ke Azure menggunakan cmdlet Azure PowerShell Connect-AzAccount , autentikasi aplikasi ke Azure menggunakan akun yang sama. Ya
7 Azure Developer CLI Jika pengembang mengautentikasi ke Azure menggunakan perintah Azure Developer CLI, autentikasi dengan akun tersebut azd auth login . Ya
8 Browser interaktif Jika diaktifkan, autentikasi pengembang secara interaktif melalui browser default sistem saat ini. Tidak

Dalam bentuk yang paling sederhana, Anda dapat menggunakan versi DefaultAzureCredential tanpa parameter sebagai berikut:

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
)

Cara menyesuaikan DefaultAzureCredential

Bagian berikut menjelaskan strategi untuk menghilangkan kredensial dari rantai.

Mengecualikan kredensial individual

Untuk mengecualikan kredensial individual dari DefaultAzureCredential, gunakan exclude yang sesuai dengan awalan. Contohnya:

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

Dalam sampel kode sebelumnya, EnvironmentCredential dan WorkloadIdentityCredential dihapus dari rantai kredensial. Akibatnya, kredensial pertama yang akan dicoba adalah ManagedIdentityCredential. Rantai yang dimodifikasi terlihat seperti ini:

Diagram yang menunjukkan alur autentikasi untuk instans DefaultAzureCredential setelah menggunakan parameter kata kunci dengan awalan 'exclude' di konstruktor untuk menghapus kredensial lingkungan dan kredensial identitas beban kerja.

Catatan

InteractiveBrowserCredential dikecualikan secara default dan oleh karena itu tidak ditampilkan dalam diagram sebelumnya. Untuk menyertakan InteractiveBrowserCredential, atur exclude_interactive_browser_credential parameter kata kunci ke False saat Anda memanggil DefaultAzureCredential konstruktor.

Semakin banyak parameter kata kunci dengan awalan exclude diatur menjadi True (pengecualian kredensial dikonfigurasi), manfaat menggunakan DefaultAzureCredential berkurang. Dalam kasus seperti itu, ChainedTokenCredential adalah pilihan yang lebih baik dan membutuhkan lebih sedikit kode. Untuk mengilustrasikan, kedua sampel kode ini berulah dengan cara yang sama:

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
)

Mengecualikan kategori jenis kredensial

Untuk mengecualikan semua Developer tool atau Deployed service kredensial, atur variabel AZURE_TOKEN_CREDENTIALS lingkungan ke prod atau dev, masing-masing. Saat nilai prod digunakan, rantai kredensial yang mendasar terlihat sebagai berikut:

Diagram yang memperlihatkan DefaultAzureCredential dengan AZURE_TOKEN_CREDENTIALS diatur ke 'prod'.

Saat nilai dev digunakan, rantai terlihat sebagai berikut:

Diagram yang memperlihatkan DefaultAzureCredential dengan AZURE_TOKEN_CREDENTIALS diatur ke 'dev'.

Penting

Variabel AZURE_TOKEN_CREDENTIALS lingkungan didukung dalam azure-identity paket versi 1.23.0 dan yang lebih baru.

Gambaran umum ChainedTokenCredential

ChainedTokenCredential adalah rantai kosong yang Anda tambahkan kredensialnya agar sesuai dengan kebutuhan aplikasi Anda. Contohnya:

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

Sampel kode sebelumnya membuat rantai kredensial yang disesuaikan yang terdiri dari dua kredensial waktu pengembangan. AzureCliCredential dicoba terlebih dahulu, diikuti oleh AzureDeveloperCliCredential, jika perlu. Dalam bentuk grafis, rantai terlihat seperti ini:

diagram yang memperlihatkan alur autentikasi untuk instans ChainedTokenCredential yang terdiri dari kredensial Azure CLI dan Azure Developer CLI.

Kiat

Untuk peningkatan performa, optimalkan pengurutan kredensial dalam ChainedTokenCredential dari kredensial yang paling banyak hingga paling sedikit digunakan.

Panduan penggunaan untuk DefaultAzureCredential

DefaultAzureCredential tidak diragukan lagi merupakan cara paling mudah untuk memulai pustaka Azure Identity, namun kemudahan tersebut membawa beberapa kompromi. Setelah menyebarkan aplikasi ke Azure, Anda harus memahami persyaratan autentikasi aplikasi. Untuk alasan itu, ganti DefaultAzureCredential dengan implementasi TokenCredential tertentu, seperti ManagedIdentityCredential.

Berikut alasannya:

  • Tantangan penelusuran kesalahan: Saat autentikasi gagal, mungkin sulit untuk melakukan debugging dan mengidentifikasi kredensial yang bermasalah. Anda harus mengaktifkan pencatatan log untuk melihat perkembangan dari satu kredensial ke kredensial berikutnya dan status keberhasilan/kegagalan masing-masing. Untuk informasi selengkapnya, lihat Men-debug kredensial yang terhubung.
  • Beban performa: Proses mencoba beberapa kredensial secara berurutan dapat menyebabkan beban pada performa. Misalnya, saat berjalan pada komputer pengembangan lokal, identitas terkelola tidak tersedia. Akibatnya, ManagedIdentityCredential selalu mengalami kegagalan di lingkungan pengembangan lokal, kecuali secara eksplisit dinonaktifkan melalui properti dengan awalan exclude yang sesuai.
  • Perilaku yang tidak dapat diprediksi: DefaultAzureCredential memeriksa keberadaan variabel lingkungan tertentu. Ada kemungkinan bahwa seseorang dapat menambahkan atau memodifikasi variabel lingkungan ini di tingkat sistem pada komputer host. Perubahan tersebut berlaku secara global dan oleh karena itu mengubah perilaku DefaultAzureCredential pada runtime di aplikasi apa pun yang berjalan di komputer tersebut.

Memecahkan masalah kredensial yang terhubung

Untuk mendiagnosis masalah yang tidak terduga atau untuk memahami apa yang dilakukan kredensial berantai, aktifkan pengelogan di aplikasi Anda. Secara opsional, filter log hanya ke peristiwa yang dikeluarkan dari pustaka klien Azure Identity. Contohnya:

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)}"
)

Untuk tujuan ilustrasi, asumsikan bentuk DefaultAzureCredential tanpa parameter digunakan untuk mengautentikasi permintaan ke akun penyimpanan blob. Aplikasi ini berjalan di lingkungan pengembangan lokal, dan pengembang diautentikasi ke Azure menggunakan Azure CLI. Asumsikan juga bahwa tingkat pengelogan diatur ke logging.DEBUG. Saat aplikasi dijalankan, entri terkait berikut muncul dalam output:

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

Pada output sebelumnya, perhatikan bahwa:

  • EnvironmentCredential, ManagedIdentityCredential, dan SharedTokenCacheCredential masing-masing gagal memperoleh token akses Microsoft Entra, dalam urutan tersebut.
  • Panggilan AzureCliCredential.get_token berhasil dan output juga menunjukkan bahwa DefaultAzureCredential memperoleh token dari AzureCliCredential. Karena AzureCliCredential berhasil, tidak ada kredensial tambahan yang dicoba.

Catatan

Dalam contoh sebelumnya, tingkat pengelogan diatur ke logging.DEBUG. Berhati-hatilah saat menggunakan tingkat pengelogan ini, karena dapat menghasilkan informasi sensitif. Misalnya, dalam hal ini, ID klien, ID penyewa, dan ID objek dari prinsipal pengguna pengembang di Azure. Semua informasi jejak balik telah dihapus dari output untuk kejelasan.