Bagikan melalui

Plugin Azure Identity untuk autentikasi broker

Paket ini menyediakan plugin ke pustaka Azure Identity 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 autentikasi Windows, Web Account Manager (WAM), yang didukung.

| Sampel Sumber | dokumentasi referensi API | [Dokumentasi ID Microsoft Entra] (https://learn.microsoft.com/entra/identity/)

Persiapan

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

useIdentityPlugin(nativeBrokerPlugin);

Prasyarat

  • Langganan Azure .

Menginstal paket

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

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

Lingkungan yang didukung

Plugin Azure Identity untuk JavaScript mendukung versi Node.js stabil (bahkan bernomor) mulai dari v18. 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 pertama kalinya Anda menggunakan @azure/identity atau ID Microsoft Entra, kami sarankan Anda membaca Menggunakan @azure/identity dengan ID Microsoft Entra terlebih dahulu. Dokumen ini akan memberi Anda pemahaman yang lebih mendalam 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, handel 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 tempat 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.

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 penggunaan aplikasi Electron untuk mengambil handel jendela, lihat sampel 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 Azure Identity [panduan pemecahan masalah][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md] 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 membuka masalah.

Berkontribusi

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

Tayangan