Pustaka klien Azure Identity untuk JavaScript - versi 3.3.0

Pustaka Azure Identity menyediakan autentikasi token Azure Active Directory (Azure AD) melalui serangkaian implementasi TokenCredential yang nyaman.

Untuk contoh berbagai kredensial, lihat halaman contoh Azure Identity.

Tautan utama:

• Kode sumber
• Paket (npm)
• Dokumentasi Referensi API
• Dokumentasi Azure AD
• Sampel

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

• 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 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 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 atas protokol autentikasi. Untuk kasus penggunaan tersebut, sebaiknya gunakan Microsoft Authentication Library untuk JavaScript (MSAL.js) secara langsung. Anda dapat membaca selengkapnya melalui tautan berikut:

• Kami menggambarkan beberapa kasus @azure/identity penggunaan tingkat lanjut 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 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.

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.

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.

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 platform Identitas Microsoft (Azure AD), baca Menggunakan @azure/identity dengan Platform Identitas Microsoft 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 Azure AD, dan menawarkan berbagai kelas kredensial yang mampu memperoleh token Azure AD 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:

1. Lingkungan - DefaultAzureCredential akan membaca informasi akun yang ditentukan melalui variabel lingkungan dan menggunakannya untuk mengautentikasi.
2. Identitas Beban Kerja - Jika aplikasi disebarkan ke 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 Developer CLI - Jika pengembang telah mengautentikasi akun melalui perintah Azure Developer CLIazd auth login, akan mengautentikasi dengan akun tersebutDefaultAzureCredential.
5. Azure CLI - Jika pengembang telah mengautentikasi akun melalui perintah Azure CLI az login , akan mengautentikasi dengan akun tersebut DefaultAzureCredential .
6. Azure PowerShell - Jika pengembang telah mengautentikasi menggunakan perintah modul Connect-AzAccount Azure PowerShell, 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, sehingga 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 dapat diprediksi yang disebarkan.

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-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 yang di-cache access_token untuk bertahan di seluruh sesi, yang berarti bahwa alur masuk interaktif tidak perlu diulang selama token yang di-cache tersedia.
• @azure/identity-vscode, yang menyediakan dependensi VisualStudioCodeCredential dan mengaktifkannya. Tanpa plugin ini, VisualStudioCodeCredential dalam paket ini akan melempar .CredentialUnavailableError Plugin menyediakan implementasi yang mendasar dari kredensial ini, memungkinkannya untuk digunakan sendiri maupun sebagai bagian dari yang DefaultAzureCredential dijelaskan di atas.

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 secara langsung untuk layanan Azure berikut ini:

• Azure App Service dan Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Struktur Layanan Azure
• Komputer Virtual Azure
• Set Skala Azure Virtual Machines

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

Konfigurasi awan

Kredensial default untuk mengautentikasi ke titik akhir Azure AD 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 dengan cepat yang berjalan di Azure.	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 identitas beban kerja Azure AD di Kubernetes.

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 Azure AD
AZURE_TENANT_ID	ID penyewa Azure AD aplikasi
AZURE_CLIENT_SECRET	salah satu rahasia klien aplikasi

Perwakilan layanan dengan sertifikat

Nama variabel	Nilai
AZURE_CLIENT_ID	ID aplikasi Azure AD
AZURE_TENANT_ID	ID penyewa Azure AD 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 Azure AD
AZURE_TENANT_ID	ID penyewa Azure AD 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 Azure AD untuk mendapatkan token akses.

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

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 Azure AD 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.