Pustaka klien Azure Identity untuk JavaScript - versi 4.1.0

Pustaka Azure Identity menyediakan autentikasi token Microsoft Entra ID (sebelumnya Azure Active Directory) melalui serangkaian implementasi TokenCredential yang nyaman.

Untuk contoh berbagai kredensial, lihat halaman contoh Identitas Azure.

Tautan utama:

Memulai

Migrasi dari v1 ke v2 dari @azure/identity

Jika Anda menggunakan v1 dari @azure/identity, lihat panduan migrasi untuk memperbarui ke v2.

Lingkungan yang didukung saat ini

  • Versi LTS dari Node.js
    • Catatan: Jika aplikasi Anda berjalan pada Node.js v8 atau lebih rendah dan Anda tidak dapat meningkatkan versi Node.js Anda ke versi stabil terbaru, maka sematkan dependensi Anda @azure/identity ke versi 1.1.0.
  • Safari, Chrome, Edge, dan Firefox versi terbaru.
    • Catatan: Di antara berbagai kredensial yang diekspor di pustaka ini, InteractiveBrowserCredential adalah satu-satunya yang didukung di browser.

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Instal paket

Instal Identitas Azure dengan npm:

npm install --save @azure/identity

Prasyarat

Kapan harus menggunakan @azure/identity

Kelas kredensial yang diekspos oleh @azure/identity difokuskan pada penyediaan cara paling mudah untuk mengautentikasi klien Azure SDK secara lokal, di lingkungan pengembangan Anda, dan dalam produksi. Kami bertujuan untuk kesederhanaan dan dukungan yang wajar dari protokol autentikasi untuk mencakup sebagian besar skenario autentikasi yang mungkin dilakukan di Azure. Kami secara aktif memperluas untuk mencakup lebih banyak skenario. Untuk daftar lengkap kredensial yang ditawarkan, lihat bagian Kelas Kredensial .

Semua jenis kredensial yang disediakan oleh @azure/identity didukung dalam Node.js. Untuk browser, InteractiveBrowserCredential adalah jenis kredensial yang akan digunakan untuk skenario autentikasi dasar.

Sebagian besar jenis kredensial yang ditawarkan dengan @azure/identity menggunakan Pustaka Autentikasi Microsoft untuk JavaScript (MSAL.js). Secara khusus, kami menggunakan pustaka MSAL.js v2, yang menggunakan Alur Kode Otorisasi OAuth 2.0 dengan PKCE dan mematuhi OpenID. Meskipun @azure/identity berfokus pada kesederhanaan, pustaka MSAL.js, seperti @azure/msal-common, @azure/msal-node, dan @azure/msal-browser, dirancang untuk memberikan dukungan yang kuat untuk protokol autentikasi yang didukung Azure.

Kapan menggunakan sesuatu yang lain

Jenis @azure/identity kredensial adalah implementasi dari kelas @azure/core-authTokenCredential. Pada prinsipnya, objek apa pun dengan getToken metode yang memenuhi getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> akan berfungsi sebagai TokenCredential. Ini berarti pengembang dapat menulis jenis kredensial mereka sendiri untuk mendukung kasus autentikasi yang tidak dicakup oleh @azure/identity. Untuk mempelajari selengkapnya, lihat Kredensial Kustom.

Meskipun jenis kredensial kami mendukung banyak kasus lanjutan, pengembang mungkin menginginkan kontrol penuh terhadap protokol autentikasi. Untuk kasus penggunaan tersebut, sebaiknya gunakan Microsoft Authentication Library untuk JavaScript (MSAL.js) secara langsung. Anda dapat membaca selengkapnya melalui tautan berikut:

Untuk alur kerja autentikasi tingkat lanjut di browser, kami memiliki bagian di mana kami menampilkan cara menggunakan pustaka browser @azure/msal secara langsung untuk mengautentikasi klien Azure SDK.

Mengautentikasi klien dalam lingkungan pengembangan

Meskipun kami merekomendasikan dalam menggunakan identitas terkelola atau autentikasi perwakilan layanan dalam aplikasi produksi Anda, biasanya pengembang menggunakan akun mereka sendiri untuk mengautentikasi panggilan ke layanan Azure saat mendebug dan mengeksekusi kode secara lokal. Ada beberapa alat pengembang yang dapat digunakan untuk melakukan autentikasi ini di lingkungan pengembangan Anda.

Mengautentikasi melalui Azure Developer CLI

Pengembang yang mengkoding di luar IDE juga dapat menggunakan [Azure Developer CLI][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][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.

Mengautentikasi melalui Azure CLI

Aplikasi yang AzureCliCredentialmenggunakan , baik secara langsung atau melalui DefaultAzureCredential, dapat menggunakan akun Azure CLI untuk mengautentikasi panggilan dalam aplikasi saat berjalan secara lokal.

Untuk mengautentikasi dengan Azure CLI pengguna dapat menjalankan perintah az login. Untuk pengguna yang menjalankan sistem dengan browser web default, Azure cli akan meluncurkan browser untuk mengautentikasi pengguna.

Info Masuk Akun Azure CLI

Untuk sistem tanpa browser web bawaan, perintah az login akan menggunakan alur autentikasi kode perangkat. Pengguna juga dapat memaksa Azure CLI untuk menggunakan alur kode perangkat daripada meluncurkan browser dengan menentukan argumen --use-device-code.

Info Masuk Kode Perangkat Akun Azure CLI

Mengautentikasi melalui Azure PowerShell

Aplikasi yang AzurePowerShellCredentialmenggunakan , baik secara langsung atau melalui DefaultAzureCredential, dapat menggunakan akun yang terhubung ke Azure PowerShell untuk mengautentikasi panggilan dalam aplikasi saat berjalan secara lokal.

Untuk mengautentikasi dengan Azure PowerShell pengguna dapat menjalankan Connect-AzAccount cmdlet . Secara default, ike Azure CLI, Connect-AzAccount akan meluncurkan browser web default untuk mengautentikasi akun pengguna.

Masuk Akun Azure PowerShell

Jika autentikasi interaktif tidak dapat didukung dalam sesi, maka -UseDeviceAuthentication argumen akan memaksa cmdlet untuk menggunakan alur autentikasi kode perangkat sebagai gantinya, mirip dengan opsi yang sesuai dalam kredensial Azure CLI.

Mengautentikasi melalui Visual Studio Code

Pengembang yang menggunakan Visual Studio Code dapat menggunakan ekstensi Akun Azure untuk mengautentikasi melalui editor. Aplikasi yang menggunakan 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 .

Selain itu, gunakan @azure/identity-vscode paket plugin. Paket ini menyediakan dependensi VisualStudioCodeCredential dan mengaktifkannya. Lihat Plugin.

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 klien di browser

Untuk mengautentikasi klien Azure SDK dalam browser web, kami menawarkan InteractiveBrowserCredential, yang dapat diatur untuk menggunakan pengalihan atau popup untuk menyelesaikan alur autentikasi. Anda perlu membuat Pendaftaran Aplikasi Azure di portal Azure untuk aplikasi web Anda terlebih dahulu.

Konsep utama

Jika ini pertama kalinya Anda menggunakan @azure/identity atau Microsoft Entra ID, baca Menggunakan @azure/identity dengan Microsoft Entra ID terlebih dahulu. Dokumen ini memberikan pemahaman yang lebih mendalam tentang platform dan cara mengonfigurasi akun Azure Anda dengan benar.

Kredensial

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

Pustaka Azure Identity berfokus pada autentikasi OAuth dengan Microsoft Entra ID, dan menawarkan berbagai kelas kredensial yang mampu memperoleh token Microsoft Entra untuk mengautentikasi permintaan layanan. Semua kelas kredensial di pustaka ini adalah penerapan dari kelas abstrak TokenCredential, dan salah satunya dapat digunakan untuk membangun klien layanan yang mampu mengautentikasi dengan TokenCredential.

Lihat Kelas Kredensial.

DefaultAzureCredential

DefaultAzureCredential sesuai untuk sebagian besar skenario di mana aplikasi dimaksudkan untuk pada akhirnya dijalankan di Azure. Ini karena DefaultAzureCredential menggabungkan kredensial yang umumnya digunakan untuk mengautentikasi saat disebarkan dengan kredensial yang digunakan untuk mengautentikasi di lingkungan pengembangan.

Catatan: DefaultAzureCredential dimaksudkan untuk menyederhanakan memulai SDK 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.

Jika digunakan dari Node.js, DefaultAzureCredential akan mencoba mengautentikasi melalui mekanisme berikut secara berurutan:

Alur autentikasi DefaultAzureCredential

  1. Lingkungan - DefaultAzureCredential akan membaca informasi akun yang ditentukan melalui variabel lingkungan dan menggunakannya untuk mengautentikasi.
  2. Identitas Beban Kerja - Jika aplikasi disebarkan untuk Azure Kubernetes Service dengan Identitas Terkelola diaktifkan, DefaultAzureCredential akan mengautentikasi dengannya.
  3. Identitas Terkelola - Jika aplikasi disebarkan ke host Azure dengan Identitas Terkelola diaktifkan, akan mengautentikasi dengan akun tersebut DefaultAzureCredential .
  4. Azure CLI - Jika pengembang telah mengautentikasi akun melalui perintah Azure CLI az login , akan mengautentikasi dengan akun tersebut DefaultAzureCredential .
  5. Azure PowerShell - Jika pengembang telah mengautentikasi menggunakan perintah modul Connect-AzAccount Azure PowerShell, akan mengautentikasi dengan akun tersebutDefaultAzureCredential.
  6. Azure Developer CLI - Jika pengembang telah mengautentikasi akun melalui perintah Azure Developer CLIazd auth login, akan mengautentikasi dengan akun tersebutDefaultAzureCredential.

Kebijakan kelanjutan

Pada versi 3.3.0, DefaultAzureCredential akan mencoba mengautentikasi dengan semua kredensial pengembang hingga berhasil, terlepas dari kesalahan yang dialami kredensial pengembang sebelumnya. Misalnya, kredensial pengembang dapat mencoba mendapatkan token dan gagal, jadi DefaultAzureCredential akan berlanjut ke kredensial berikutnya dalam alur. Kredensial layanan yang disebarkan akan menghentikan alur dengan pengecualian yang dilemparkan jika mereka dapat mencoba pengambilan token, tetapi tidak menerimanya.

Ini memungkinkan untuk mencoba semua kredensial pengembang di komputer Anda sambil memiliki perilaku yang disebarkan yang dapat diprediksi.

Catatan tentang VisualStudioCodeCredential

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

Plugin

Azure Identity for JavaScript menyediakan API plugin yang memungkinkan kami menyediakan fungsionalitas tertentu melalui paket plugin terpisah. Paket mengekspor @azure/identity fungsi tingkat atas (useIdentityPlugin) yang dapat digunakan untuk mengaktifkan plugin. Kami menyediakan dua paket plugin:

  • @azure/identity-broker, yang menyediakan dukungan autentikasi broker melalui broker asli, seperti Pengelola Akun Web.
  • @azure/identity-cache-persistence, yang menyediakan penembolokan token persisten di Node.js menggunakan sistem penyimpanan aman asli yang disediakan oleh sistem operasi Anda. Plugin ini memungkinkan nilai cache access_token bertahan di seluruh sesi, yang berarti bahwa alur masuk interaktif tidak perlu diulang selama token yang di-cache tersedia.

Contoh

Anda dapat menemukan lebih banyak contoh tentang menggunakan berbagai kredensial di Halaman Contoh Identitas Azure

Mengautentikasi dengan DefaultAzureCredential

Contoh ini menunjukkan autentikasi KeyClient dari pustaka klien @azure/keyvault-keys menggunakan DefaultAzureCredential.

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.

// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";

// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

Tentukan identitas terkelola yang ditetapkan pengguna dengan DefaultAzureCredential

Skenario yang relatif umum melibatkan autentikasi menggunakan identitas terkelola yang ditetapkan pengguna untuk sumber daya Azure. Jelajahi contoh tentang Mengautentikasi identitas terkelola yang ditetapkan pengguna dengan DefaultAzureCredential untuk melihat bagaimana ini dibuat tugas yang relatif mudah yang dapat dikonfigurasi menggunakan variabel lingkungan atau dalam kode.

Menentukan alur autentikasi kustom dengan ChainedTokenCredential

Meskipun DefaultAzureCredential umumnya merupakan cara tercepat guna mulai mengembangkan aplikasi untuk Azure, pengguna yang lebih mahir mungkin ingin menyesuaikan kredensial yang dipertimbangkan saat mengautentikasi. ChainedTokenCredential memungkinkan pengguna menggabungkan beberapa instans kredensial untuk menentukan rantai kredensial yang disesuaikan. Contoh ini menunjukkan pembuatan ChainedTokenCredential yang akan mencoba mengautentikasi menggunakan dua instans yang dikonfigurasi secara berbeda dari ClientSecretCredential, untuk kemudian mengautentikasi KeyClient dari @azure/keyvault-keys:

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

// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);

// The chain can be used anywhere a credential is required
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);

Dukungan identitas terkelola

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

Untuk contoh cara menggunakan identitas terkelola untuk autentikasi, lihat contohnya.

Konfigurasi awan

Kredensial default untuk mengautentikasi ke titik akhir Microsoft Entra untuk Azure Public Cloud. Untuk mengakses sumber daya di cloud lain, seperti Azure Government atau cloud privat, konfigurasikan kredensial dengan authorityHost argumen di konstruktor. Antarmuka AzureAuthorityHosts mendefinisikan otoritas untuk cloud terkenal. Untuk cloud Pemerintah AS, Anda dapat membuat instans kredensial dengan cara ini:

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

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

Kelas kredensial

Mengautentikasi aplikasi yang dihosting Azure

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

Mengautentikasi perwakilan layanan

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

Autentikasi pengguna

Kredensial Penggunaan Contoh Referensi
AuthorizationCodeCredential Mengautentikasi pengguna dengan kode otorisasi yang diperoleh sebelumnya. contoh Kode autentikasi OAuth2
DeviceCodeCredential Mengautentikasi pengguna secara interaktif pada perangkat dengan antarmuka pengguna yang terbatas. contoh Autentikasi kode perangkat
InteractiveBrowserCredential Mengautentikasi pengguna secara interaktif dengan browser sistem default. Baca selengkapnya tentang bagaimana hal ini terjadi di sini. contoh 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. contoh Autentikasi nama pengguna + kata sandi

Mengautentikasi melalui alat pengembangan

Kredensial Penggunaan Contoh Referensi
AzureCliCredential Mengautentikasi dalam lingkungan pengembangan dengan Azure CLI. contoh Autentikasi Azure CLI
AzureDeveloperCliCredential Autentikasi di lingkungan pengembangan dengan pengguna atau perwakilan layanan yang diaktifkan di Azure Developer CLI. Referensi Azure Developer CLI
AzurePowerShellCredential Autentikasi di lingkungan pengembangan menggunakan Azure PowerShell. contoh 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 Microsoft Entra
AZURE_TENANT_ID ID penyewa Microsoft Entra aplikasi
AZURE_CLIENT_SECRET salah satu rahasia klien aplikasi

Perwakilan layanan dengan sertifikat

Nama variabel Nilai
AZURE_CLIENT_ID ID aplikasi Microsoft Entra
AZURE_TENANT_ID ID penyewa Microsoft Entra aplikasi
AZURE_CLIENT_CERTIFICATE_PATH jalur ke file sertifikat yang dikodekan PEM 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 Microsoft Entra
AZURE_TENANT_ID ID penyewa Microsoft Entra aplikasi
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.

Evaluasi Akses Berkelanjutan

Pada versi 3.3.0, mengakses sumber daya yang dilindungi oleh Evaluasi Akses Berkelanjutan (CAE) dimungkinkan berdasarkan per permintaan. Ini dapat diaktifkan menggunakan GetTokenOptions.enableCae(boolean) API. CAE tidak didukung untuk kredensial pengembang.

Penembolokan token

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

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

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

Autentikasi broker

Broker autentikasi adalah aplikasi yang berjalan pada mesin pengguna dan mengelola jabat tangan autentikasi dan pemeliharaan token untuk akun yang terhubung. Saat ini, hanya Pengelola Akun Web Windows (WAM) yang didukung. Untuk mengaktifkan dukungan, gunakan @azure/identity-broker paket . Untuk detail tentang mengautentikasi menggunakan WAM, lihat dokumentasi plugin broker.

Pemecahan Masalah

Untuk bantuan terkait pemecahan masalah, lihat panduan pemecahan masalah.

Langkah berikutnya

Membaca dokumentasi

Dokumentasi API untuk pustaka ini dapat ditemukan di situs dokumentasi kami.

Dukungan pustaka klien

Pustaka klien dan manajemen tercantum di halaman rilis Azure SDK yang mendukung autentikasi Microsoft Entra menerima kredensial dari pustaka ini. Pelajari selengkapnya tentang menggunakan pustaka ini dalam dokumentasinya, yang ditautkan dari halaman rilis.

Masalah yang diketahui

Dukungan Azure Active Directory B2C

Pustaka ini tidak mendukung layanan Azure AD B2C.

Untuk masalah terbuka lainnya, lihat repositori GitHub pustaka.

Berikan umpan balik

Jika Anda menemukan bug atau memiliki saran, buka masalah.

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Tayangan