Plugin Azure Identity untuk autentikasi perantara

Paket ini menyediakan plugin ke pustaka Identitas Azure untuk JavaScript (@azure/identity) yang memungkinkan penggunaan broker autentikasi seperti WAM.

Broker autentikasi adalah aplikasi yang berjalan pada komputer pengguna yang mengelola jabat tangan autentikasi dan pemeliharaan token untuk akun yang terhubung. Saat ini, hanya broker Windows authentication, Web Account Manager (WAM), yang didukung.

Kode sumber | Sampel | Dokumentasi referensi API | Microsoft Entra ID dokumentasi

Persiapan

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

Prasyarat

Catatan: Untuk pengembangan lokal dengan @azure/identity-broker, Anda mungkin perlu menginstal alat tambahan. node-gyp digunakan untuk mengkompilasi add-on untuk mengakses API sistem. Persyaratan instalasi tercantum dalam node-gyp README.

Di Linux, perpustakaan menggunakan libsecret sehingga Anda mungkin perlu menginstalnya. Bergantung pada distribusi Anda, Anda harus menjalankan perintah berikut:

  • Debian/Ubuntu: sudo apt-get install libsecret-1-dev
  • Berbasis Red Hat: sudo yum install libsecret-devel
  • Lengkungan Linux: sudo pacman -S libsecret

Nota

Autentikasi perantara saat ini hanya didukung di Windows dan Linux. macOS belum didukung.

Menginstal paket

Paket ini dirancang untuk digunakan dengan Azure Identity untuk JavaScript. Instal @azure/identity dan paket ini menggunakan npm:

npm install --save @azure/identity
npm install --save @azure/identity-broker

Lingkungan yang didukung

Azure Plugin identitas untuk JavaScript mendukung versi Node.js yang stabil (bernomor genap) mulai dari v20. Meskipun plugin dapat berjalan dalam versi Node.js lainnya, tidak ada dukungan yang dijamin. @azure/identity-broker tidak mendukung lingkungan browser.

Konsep utama

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

Handel jendela induk

Saat mengautentikasi dengan broker melalui InteractiveBrowserCredential, handel jendela induk diperlukan untuk memastikan bahwa dialog autentikasi ditampilkan dengan benar di atas jendela permintaan. Dalam konteks antarmuka pengguna grafis pada perangkat, handel jendela adalah pengidentifikasi unik yang ditetapkan sistem operasi ke setiap jendela. Untuk sistem operasi Windows, pegangan ini adalah nilai bilangan bulat yang berfungsi sebagai referensi ke jendela tertentu.

Passthrough akun Microsoft (MSA)

Akun Microsoft (MSA) adalah akun pribadi yang dibuat oleh pengguna untuk mengakses layanan Microsoft. Passthrough MSA adalah konfigurasi warisan yang memungkinkan pengguna untuk mendapatkan token ke sumber daya yang biasanya tidak menerima login MSA. Fitur ini hanya tersedia untuk aplikasi pihak pertama. Pengguna yang mengautentikasi dengan aplikasi yang dikonfigurasi untuk menggunakan passthrough MSA dapat mengatur legacyEnableMsaPassthrough ke true di dalam InteractiveBrowserCredentialNodeOptions.brokerOptions untuk memungkinkan akun pribadi ini dicantumkan oleh WAM.

URI Pengalihan

Aplikasi Microsoft Entra mengandalkan URI pengalihan untuk menentukan ke mana harus mengirim respons autentikasi setelah pengguna masuk. Untuk mengaktifkan autentikasi broker melalui WAM, URI pengalihan yang cocok dengan pola berikut harus didaftarkan ke aplikasi:

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Plugin Azure Identity

Pada @azure/identity versi 2.0.0, pustaka klien Identitas untuk JavaScript menyertakan API plugin. Paket ini (@azure/identity-broker) mengekspor objek plugin yang harus Anda teruskan sebagai argumen ke fungsi useIdentityPlugin tingkat atas dari paket @azure/identity. Aktifkan broker asli dalam program Anda sebagai berikut:

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

Setelah memanggil useIdentityPlugin, plugin broker asli terdaftar ke paket @azure/identity dan akan tersedia di InteractiveBrowserCredential yang mendukung autentikasi broker WAM. Kredensial ini memiliki brokerOptions dalam opsi konstruktor.

Catatan: Mulai @azure/identity versi 4.11.0-beta.1, DefaultAzureCredential menyediakan dukungan untuk masuk melalui Pengelola Akun Web Windows. Aktifkan broker asli dalam program Anda sebagai berikut:

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

Contoh

Setelah plugin terdaftar, Anda dapat mengaktifkan autentikasi broker WAM dengan meneruskan brokerOptions dengan properti enabled diatur ke true ke konstruktor kredensial. Dalam contoh berikut, kita menggunakan InteractiveBrowserCredential.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");

Untuk contoh lengkap menggunakan aplikasi Electron untuk mengambil pegangan jendela, lihat contoh ini.

Menggunakan akun default untuk masuk

Ketika opsi useDefaultBrokerAccount diatur ke true, kredensial akan mencoba menggunakan akun broker default secara diam-diam. Jika menggunakan akun default gagal, kredensial akan kembali ke autentikasi interaktif.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    useDefaultBrokerAccount: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";

// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");

Pemecahan masalah

Lihat panduan pemecahan masalah Azure Identity untuk detail tentang cara mendiagnosis berbagai skenario kegagalan.

Penebangan

Mengaktifkan pengelogan dapat membantu mengungkap informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Langkah berikutnya

Berikan umpan balik

Jika Anda mengalami bug atau memiliki saran, silakan buka masalah.

Berkontribusi

Jika Anda ingin berkontribusi ke library ini, lihat panduan contributoring untuk mempelajari lebih lanjut cara membuat dan menguji kode.

  • Last updated on