Rantai kredensial di perpustakaan Azure Identity untuk Java

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

Cara kerja kredensial berantai

Saat runtime, rantai kredensial berusaha mengautentikasi 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:

Mengapa menggunakan rantai kredensial

Kredensial berantai dapat menawarkan manfaat berikut:

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

  import com.azure.core.credential.TokenCredential;
  import com.azure.identity.AzureCliCredentialBuilder;
  import com.azure.identity.ManagedIdentityCredentialBuilder;
  
  // Code omitted for brevity
  
  TokenCredential credential = null;
  
  // Set up credential based on environment (Azure or local development)
  String environment = System.getenv("ENV");
  
  if (environment != null && environment.equals("production")) {
      credential = new ManagedIdentityCredentialBuilder()
          .clientId(userAssignedClientId)
          .build();
  } else {
      credential = new AzureCliCredentialBuilder()
          .build();
  }
  

• 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 untuk pengaitan kredensial:

• Gunakan rantai yang telah dikonfigurasi dan disusun sebelumnya: Mulailah dengan rantai baku yang telah disiapkan untuk mengakomodasi skenario autentikasi yang paling umum. Untuk pendekatan ini, lihat bagian ikhtisar DefaultAzureCredential.
• "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 dikonfigurasi sebelumnya dengan preferensi tertentu. 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:

Urutan di mana DefaultAzureCredential menguji kredensial adalah sebagai berikut.

Pesanan	Kredensial	Deskripsi
1	Lingkungan	Membaca sekumpulan variabel lingkungan untuk menentukan apakah perwakilan layanan aplikasi (pengguna aplikasi) telah 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.
2	Identitas Beban Kerja	Jika aplikasi disebarkan ke host Azure dengan Identitas Beban Kerja diaktifkan, autentikasi akun tersebut.
3	Identitas Terkelola	Jika aplikasi disebarkan ke host Azure dengan Identitas Terkelola diaktifkan, autentikasi aplikasi ke Azure menggunakan Identitas Terkelola tersebut.
4	IntelliJ	Jika pengembang mengautentikasi melalui Azure Toolkit untuk IntelliJ, autentikasi akun tersebut.
5	Visual Studio Code	Jika pengembang mengautentikasi melalui ekstensi Sumber Daya Azure Visual Studio Code dan paket azure-identity-broker diinstal, autentikasi akun tersebut.
6	Azure CLI	Jika pengembang mengautentikasi ke Azure menggunakan perintah Azure CLI az login , autentikasi aplikasi ke Azure menggunakan akun yang sama.
7	Azure PowerShell	Jika pengembang mengautentikasi ke Azure menggunakan cmdlet Azure PowerShell Connect-AzAccount , autentikasi aplikasi ke Azure menggunakan akun yang sama.
8	Azure Developer CLI	Jika pengembang mengautentikasi ke Azure menggunakan perintah Azure Developer CLI, autentikasi dengan akun tersebut azd auth login .
9	Pialang	Mengautentikasi menggunakan akun default yang telah masuk ke OS melalui broker. Mengharuskan paket azure-identity-broker diinstal, karena instans InteractiveBrowserCredential yang diaktifkan broker digunakan.

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

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

Cara menyesuaikan DefaultAzureCredential

Bagian berikut menjelaskan strategi untuk mengontrol kredensial mana yang disertakan dalam rantai.

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:

Saat nilai dev digunakan, rantai terlihat sebagai berikut:

Penting

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

Untuk memastikan variabel lingkungan ditentukan dan diatur ke string yang didukung, panggil metode requireEnvVars sebagai berikut:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Menggunakan kredensial tertentu

Untuk mengecualikan semua kredensial kecuali satu, atur variabel AZURE_TOKEN_CREDENTIALS lingkungan ke nama kredensial. Misalnya, Anda dapat mengurangi DefaultAzureCredential rantai menjadi AzureCliCredential dengan mengatur AZURE_TOKEN_CREDENTIALS ke AzureCliCredential. Perbandingan string dilakukan dengan cara yang tidak peka huruf besar/kecil. Nilai string yang valid untuk variabel lingkungan meliputi:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Penting

Variabel AZURE_TOKEN_CREDENTIALS lingkungan mendukung nama kredensial individual dalam azure-identity paket versi 1.17.0 dan yang lebih baru.

Untuk memastikan variabel lingkungan ditentukan dan diatur ke string yang didukung, metode panggilan requireEnvVars sebagai berikut:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Gambaran umum ChainedTokenCredential

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

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(cliCredential)
    .addLast(ijCredential)
    .build();

Sampel kode sebelumnya membuat rantai kredensial yang dirancang khusus yang terdiri dari dua kredensial pada saat pengembangan. AzureCliCredential dicoba terlebih dahulu, diikuti oleh IntelliJCredential, jika perlu. Dalam bentuk grafis, rantai terlihat seperti ini:

diagram

Petunjuk

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 adalah cara paling mudah untuk memulai dengan pustaka Azure Identity, tetapi dengan kenyamanan itu ada 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 debug dan mengidentifikasi kredensial yang salah. Anda harus mengaktifkan pencatatan log untuk melihat perkembangan dari satu kredensial ke kredensial berikutnya dan status keberhasilan/kegagalan masing-masing. Untuk informasi selengkapnya, lihat Debugging kredensial berantai.
• Overhead performa: Proses mencoba beberapa identitas secara berurutan dapat mengakibatkan penurunan performa. Misalnya, saat berjalan pada komputer pengembangan lokal, identitas terkelola tidak tersedia. Akibatnya, ManagedIdentityCredential selalu gagal di lingkungan pengembangan lokal.
• 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.

Menyelidiki kredensial berantai

Untuk mendiagnosis masalah yang tidak terduga atau untuk memahami apa yang dilakukan kredensial berantai, aktifkan pengelogan di aplikasi Anda.

Untuk tujuan ilustrasi, asumsikan bentuk DefaultAzureCredential tanpa parameter digunakan untuk mengautentikasi permintaan ke akun Blob Storage. Aplikasi ini berjalan di lingkungan pengembangan lokal, dan pengembang diautentikasi ke Azure menggunakan Azure CLI. Saat aplikasi dijalankan, entri terkait berikut muncul dalam output:

[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

Pada output sebelumnya, perhatikan bahwa:

• EnvironmentCredential, , WorkloadIdentityCredential, ManagedIdentityCredentialIntelliJCredential, dan VisualStudioCodeCredential masing-masing gagal memperoleh token akses Microsoft Entra, dalam urutan tersebut.
• Panggilan AzureCliCredential.getToken berhasil, seperti yang ditunjukkan oleh entri yang berakhiran returns a token. Setelah AzureCliCredential berhasil, tidak ada kredensial lain yang dicoba.