Pustaka klien Azure Identity untuk JavaScript - versi 4.8.0

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

Untuk contoh berbagai kredensial, lihat halaman contoh Azure Identity.

Tautan kunci:

• Kode sumber
• Paket (npm)
• Dokumentasi Referensi API
• Microsoft Entra Dokumentasi ID
• Sampel

Persiapan

Lingkungan yang saat ini didukung

• versi LTS Node.js
• Versi terbaru Safari, Chrome, Edge, dan Firefox.
  • Catatan: Di antara berbagai kredensial yang diekspor di pustaka ini, InteractiveBrowserCredential adalah satu-satunya yang didukung di browser.

Untuk informasi selengkapnya, lihat kebijakan dukungan kami.

Menginstal paket

Instal Azure Identity dengan npm:

npm install --save @azure/identity

Prasyarat

• Langganan Azure.
• Opsional: Azure CLI dan/atau Azure PowerShell juga dapat berguna untuk mengautentikasi di lingkungan pengembangan dan mengelola peran akun.

Kapan harus menggunakan @azure/identity

Kelas info masuk yang diekspos oleh @azure/identity berfokus 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 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 di Node.js. Untuk browser, InteractiveBrowserCredential adalah jenis kredensial yang akan digunakan untuk skenario autentikasi dasar.

Sebagian besar jenis kredensial yang ditawarkan oleh @azure/identity menggunakan Microsoft Authentication Library for JavaScript (MSAL.js). Secara khusus, kami menggunakan pustaka MSAL.js v2, yang menggunakan Alur Kode Otorisasi OAuth 2.0 dengan PKCE dan yang mematuhi OpenID . Meskipun 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 kredensial adalah implementasi kelas @azure/core-auth. Pada prinsipnya, objek apa pun dengan metode getToken yang memenuhi getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> 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 skenario tingkat lanjut, pengembang mungkin ingin menggunakan Microsoft Authentication Library for JavaScript (MSAL.js) secara langsung sebagai gantinya. Pertimbangkan untuk menggunakan MSAL.js dalam skenario berikut:

• Pengembang yang menginginkan kontrol penuh terhadap protokol autentikasi dan konfigurasinya.
• Jenis kredensial kami dirancang untuk digunakan dengan klien Azure SDK dengan penembolokan cerdas dan penyegaran token yang ditangani di lapisan HTTP inti. Jika Anda merasa harus menggunakan getToken secara langsung, Anda mungkin mendapat manfaat menggunakan MSAL.js untuk kontrol lebih besar atas alur autentikasi dan penembolokan token.

Anda dapat membaca selengkapnya melalui tautan berikut:

• Kami menggambarkan beberapa kasus penggunaan lanjutan di halaman Contoh Identitas Azure .
  • Di sana, kami secara khusus memiliki bagian Contoh Tingkat Lanjut .
  • Kami juga memiliki bagian yang menunjukkan cara Mengautentikasi dengan MSAL secara langsung.

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 di lingkungan pengembangan

Meskipun sebaiknya gunakan identitas terkelola di aplikasi yang dihosting Azure Anda, biasanya pengembang menggunakan akun mereka sendiri untuk mengautentikasi panggilan ke layanan Azure saat men-debug dan menjalankan kode secara lokal. Ada beberapa alat pengembang yang dapat digunakan untuk melakukan autentikasi ini di lingkungan pengembangan Anda.

Mengautentikasi melalui Azure Developer CLI

Pengkodian pengembang di luar IDE juga dapat menggunakan CLI Pengembang Azure untuk mengautentikasi. Aplikasi yang menggunakan DefaultAzureCredential atau AzureDeveloperCliCredential kemudian dapat menggunakan akun ini untuk mengautentikasi panggilan dalam aplikasi mereka saat berjalan secara lokal.

Untuk mengautentikasi denganCLI Pengembang Azure , pengguna dapat menjalankan perintah . Untuk pengguna yang berjalan pada sistem dengan browser web default, Azure Developer CLI meluncurkan browser untuk mengautentikasi pengguna.

Untuk sistem tanpa browser web default, perintah azd auth login --use-device-code menggunakan alur autentikasi kode perangkat.

Mengautentikasi melalui Azure CLI

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

Untuk mengautentikasi denganAzure CLI , jalankan perintah . Untuk pengguna yang berjalan pada sistem dengan browser web default, Azure CLI meluncurkan browser untuk mengautentikasi pengguna.

Masuk Akun Azure CLI

Untuk sistem tanpa browser web default, perintah az login 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.

Masuk Kode Perangkat Akun Azure CLI

Mengautentikasi melalui Azure PowerShell

Aplikasi yang menggunakan AzurePowerShellCredential, 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 denganAzure PowerShell , jalankan cmdlet . Secara default, seperti Azure CLI, Connect-AzAccount meluncurkan browser web default untuk mengautentikasi akun pengguna.

Masuk Akun Azure PowerShell

Jika autentikasi interaktif tidak dapat didukung dalam sesi, maka argumen -UseDeviceAuthentication memaksa cmdlet untuk menggunakan alur autentikasi kode perangkat sebagai gantinya, mirip dengan opsi yang sesuai dalam kredensial 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 Microsoft Azure untuk aplikasi web Anda terlebih dahulu.

Konsep utama

Jika ini pertama kalinya Anda menggunakan @azure/identity atau ID Microsoft Entra, baca Menggunakan @azure/identity dengan ID Microsoft Entra 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 untuk 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 ID Microsoft Entra, dan menawarkan berbagai kelas info masuk yang mampu memperoleh token Microsoft Entra untuk mengautentikasi permintaan layanan. Semua kelas kredensial di pustaka ini adalah implementasi dari kelas abstrak TokenCredential, dan salah satunya dapat digunakan oleh untuk membangun klien layanan yang mampu mengautentikasi dengan TokenCredential.

LihatKelas Kredensial .

DefaultAzureCredential

DefaultAzureCredential menyederhanakan autentikasi saat mengembangkan aplikasi yang disebarkan ke Azure dengan menggabungkan kredensial yang digunakan di lingkungan hosting Azure dengan kredensial yang digunakan dalam pengembangan lokal. Untuk informasi selengkapnya, lihat Gambaran umum DefaultAzureCredential.

Kebijakan kelanjutan

Pada versi 3.3.0, DefaultAzureCredential 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 berlanjut ke kredensial berikutnya dalam alur. Kredensial layanan yang disebarkan 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 diketahui, VisualStudioCodeCredential telah dihapus dari rantai token DefaultAzureCredential. 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 @azure/identity mengekspor 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 access_token yang di-cache untuk 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 penggunaan berbagai kredensial di Halaman Contoh Identitas Azure

Mengautentikasi dengan DefaultAzureCredential

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

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";

// 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 hal ini dibuat sebagai tugas yang relatif mudah yang dapat dikonfigurasi menggunakan variabel lingkungan atau dalam kode.

Menentukan alur autentikasi kustom dengan ChainedTokenCredential

Meskipun DefaultAzureCredential umumnya adalah cara tercepat untuk mulai mengembangkan aplikasi untuk Azure, pengguna yang lebih canggih 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 mencoba mengautentikasi menggunakan dua instans ClientSecretCredentialyang dikonfigurasi secara berbeda , untuk kemudian mengautentikasi KeyClient dari @azure/keyvault-keys:

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";

// 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
const client = new KeyClient(vaultUrl, credentialChain);

Dukungan identitas terkelola

autentikasi identitas terkelola didukung melalui atau kelas kredensial secara langsung untuk layanan Azure berikut:

• Azure App Service dan Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines
• Set Skala Azure Virtual Machines

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

Konfigurasi cloud

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 argumen authorityHost di konstruktor. Enum AzureAuthorityHosts mendefinisikan otoritas untuk cloud terkenal. Untuk cloud Pemerintah AS, Anda dapat membuat instans kredensial dengan cara ini:

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

Sebagai alternatif untuk menentukan argumen authorityHost, Anda juga dapat mengatur variabel lingkungan AZURE_AUTHORITY_HOST ke URL otoritas cloud Anda. Pendekatan ini berguna saat mengonfigurasi beberapa kredensial untuk mengautentikasi ke cloud yang sama atau ketika lingkungan yang disebarkan perlu menentukan cloud target:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

Enum AzureAuthorityHosts mendefinisikan otoritas untuk cloud terkenal demi kenyamanan Anda; namun, jika otoritas untuk cloud Anda tidak tercantum dalam AzureAuthorityHosts, Anda dapat meneruskan URL otoritas yang valid sebagai argumen string. Contohnya:

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

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

Kelas kredensial

Rantai kredensial

Mengautentikasi aplikasi yang dihosting Azure

Mengautentikasi perwakilan layanan

Mengautentikasi pengguna

Mengautentikasi melalui alat pengembangan

Variabel lingkungan

DefaultAzureCredential dan EnvironmentCredential dapat dikonfigurasi dengan variabel lingkungan. Setiap jenis autentikasi memerlukan nilai untuk variabel tertentu.

Perwakilan layanan dengan rahasia

Perwakilan layanan dengan sertifikat

Konfigurasi dicoba dalam urutan sebelumnya. Misalnya, jika nilai untuk rahasia dan sertifikat klien keduanya ada, maka digunakan rahasia klien.

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 API GetTokenOptions.enableCae(boolean). 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 ID Microsoft Entra untuk mendapatkan token akses.

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

Autentikasi broker

Broker autentikasi adalah aplikasi yang berjalan pada komputer 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 paket @azure/identity-broker. 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 yang 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 AD B2C

Pustaka ini tidak mendukung layanan Azure AD B2C .

Untuk masalah terbuka lainnya, lihat repositori GitHub pustaka.

Berikan umpan balik

Jika Anda mengalami bug atau memiliki saran, membuka masalah.

Berkontribusi

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