Rantai kredensial di pustaka Identitas Azure untuk JavaScript

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

Selama runtime, rantai kredensial mencoba 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 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:

  import { 
      ManagedIdentityCredential, 
      AzureCliCredential 
  } from "@azure/identity";
  
  let credential;
  if (process.env.NODE_ENV === "production") {
      credential = new ManagedIdentityCredential();
  } else {
      credential = new 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 pendekatan berbeda untuk 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 disarankan dan telah dikonfigurasi 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:

Urutan di mana DefaultAzureCredential mencoba kredensial adalah sebagai berikut.

Pesanan	Bukti Identitas	Deskripsi	Aktifkan secara default?
1	Lingkungan	Membaca kumpulan variabel lingkungan untuk menentukan apakah perwakilan layanan aplikasi (pengguna aplikasi) dikonfigurasi untuk aplikasi. Jika demikian, DefaultAzureCredential menggunakan nilai-nilai ini untuk mengautentikasi aplikasi ke Azure. Metode ini paling sering digunakan di lingkungan server tetapi juga dapat digunakan saat mengembangkan secara lokal.	Yes
2	Identitas Beban Kerja	Jika aplikasi disebarkan ke host Azure dengan Identitas Beban Kerja diaktifkan, autentikasi akun tersebut.	Yes
3	Identitas Terkelola	Jika aplikasi disebarkan ke host Azure dengan Identitas Terkelola diaktifkan, autentikasi aplikasi ke Azure menggunakan Identitas Terkelola tersebut.	Yes
4	Visual Studio Code	Jika pengembang mengautentikasi melalui ekstensi Sumber Daya Azure Visual Studio Code dan paket @azure/identity-vscode diinstal, autentikasi akun tersebut.	Yes
5	Azure CLI	Jika pengembang diautentikasi ke Azure menggunakan perintah az login Azure CLI, autentikasi aplikasi ke Azure menggunakan akun yang sama.	Yes
6	Azure PowerShell	Jika pengembang mengautentikasi ke Azure menggunakan cmdlet Connect-AzAccount Azure PowerShell, autentikasi aplikasi ke Azure menggunakan akun yang sama.	Yes
7	Azure Developer CLI	Jika pengembang mengautentikasi ke Azure menggunakan perintah azd auth login Azure Developer CLI, autentikasi dengan akun tersebut.	Yes
8	Pialang	Mengautentikasi menggunakan akun default yang telah masuk ke OS melalui broker. Mengharuskan paket @azure/identity-broker diinstal.	Yes

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

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

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:

Untuk memastikan variabel lingkungan ditentukan dan diatur ke string yang didukung, atur properti requiredEnvVars ke AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

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
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Penting

Variabel AZURE_TOKEN_CREDENTIALS lingkungan mendukung nama kredensial individual dalam @azure/identity paket versi 4.11.0 dan yang lebih baru.

Untuk memastikan variabel lingkungan ditentukan dan diatur ke string yang didukung, atur properti requiredEnvVars ke AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Gambaran umum ChainedTokenCredential

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

import { 
    ChainedTokenCredential, 
    AzureCliCredential, 
    VisualStudioCodeCredential 
} from "@azure/identity";

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

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

Tips

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 debugging: Ketika autentikasi gagal, mungkin sulit untuk men-debug dan mengidentifikasi kredensial yang menyinggung. 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.
• 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 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.

Memecahkan masalah kredensial

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

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

Pada output sebelumnya, perhatikan bahwa DefaultAzureCredential berhasil memperoleh token menggunakan AzureCliCredential.