Rantai kredensial di pustaka identitas Azure untuk Java

Pustaka identitas Azure menyediakan kredensial—kelas publik yang mengimplementasikan antarmuka TokenCredential dari pustaka Azure Core. Kredensial mewakili alur autentikasi yang berbeda untuk memperoleh token akses dari Microsoft Entra ID. 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 pendekatan berbeda untuk rantai 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 kumpulan variabel lingkungan untuk menentukan apakah perwakilan layanan aplikasi (pengguna aplikasi) telah dikonfigurasi untuk aplikasi. Jika demikian, DefaultAzureCredential menggunakan nilai-nilai ini untuk mengautentikasi aplikasi untuk Azure. Metode ini dapat digunakan saat mengembangkan secara lokal, tetapi paling sering digunakan di lingkungan server.
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 untuk 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 Azure Resources Visual Studio Code dan paket azure-identity-broker diinstal, autentikasi akun tersebut.
6	Azure CLI	Jika pengembang mengautentikasi untuk Azure menggunakan perintah az login Azure CLI, autentikasi aplikasi untuk Azure menggunakan akun yang sama.
7	Azure PowerShell	Jika pengembang mengautentikasi untuk Azure menggunakan cmdlet Connect-AzAccount Azure PowerShell, autentikasi aplikasi untuk Azure menggunakan akun yang sama.
8	Azure Developer CLI	Jika pengembang mengautentikasi untuk Azure menggunakan perintah azd auth login Azure Developer CLI, autentikasi dengan akun tersebut.
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();

Penting

Metode requireEnvVars ini tersedia dalam azure-identity paket versi 1.18.0 dan yang lebih baru.

Untuk menggunakan nama variabel lingkungan kustom alih-alih default AZURE_TOKEN_CREDENTIALS, gunakan AzureIdentityEnvVars.fromString() untuk membuat referensi ke variabel kustom Anda:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
    .build();

Nota

Metode requireEnvVars mengeluarkan IllegalStateException jika variabel lingkungan yang ditentukan tidak didefinisikan atau kosong.

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 tanpa membedakan antara huruf besar dan 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();

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

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 termudah untuk memulai dengan pustaka identitas Azure, tetapi dengan kenyamanan itu datang kompromi. Setelah menyebarkan aplikasi ke Azure, Anda harus memahami persyaratan autentikasi aplikasi dan mempertimbangkan apakah DefaultAzureCredential sesuai untuk skenario Anda.

DefaultAzureCredential menawarkan manfaat utama: ini memisahkan kode aplikasi Anda dari mekanisme autentikasi tertentu, memungkinkan Anda mengubah konfigurasi autentikasi tanpa memodifikasi kode. Untuk pengembang berpengalaman yang secara sadar mengonfigurasi autentikasi produksi mereka, fleksibilitas ini bisa berharga. Namun, fleksibilitas ini dilengkapi dengan potensi kelemahan:

• 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.
• Ketidakcocokan izin: DefaultAzureCredential proses berhenti pada kredensial pertama yang berhasil memperoleh token, walaupun kredensial tersebut mungkin tidak memiliki izin yang benar. Misalnya, kredensial pengembangan lokal mungkin memiliki izin yang lebih luas daripada identitas terkelola produksi, menyebabkan aplikasi berfungsi secara lokal tetapi gagal pemeriksaan otorisasi setelah penyebaran.

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 tanpa parameter DefaultAzureCredential digunakan untuk mengautentikasi permintaan ke akun Blob Storage. Aplikasi berjalan di lingkungan pengembangan lokal, dan pengembang diautentikasi untuk 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, ManagedIdentityCredential, IntelliJCredential, 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.