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.

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

Memulai

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

useIdentityPlugin(nativeBrokerPlugin);

Prasyarat

• Langganan Azure.

Instal paketnya

Paket ini dirancang untuk digunakan dengan Azure Identity for JavaScript. Instal dan @azure/identity 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 di versi Node.js lainnya, tidak ada dukungan yang dijamin. @azure/identity-brokertidak 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 diatur legacyEnableMsaPassthrough ke true 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 tingkat useIdentityPlugin atas dari @azure/identity paket. Aktifkan broker asli dalam program Anda sebagai berikut:

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
  },
});

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

Contoh

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

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

  // 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), "...");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

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

Menggunakan akun default untuk masuk

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

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      useDefaultBrokerAccount: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

  // 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), "...");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Pemecahan Masalah

Lihat Azure Identity [panduan pemecahan masalah][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.0.1/sdk/identity/identity/TROUBLESHOOTING.md] untuk detail tentang cara mendiagnosis berbagai skenario kegagalan.

Pencatatan

Mengaktifkan pengelogan dapat membantu menemukan 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 menemukan bug atau memiliki saran, buka masalah.

Berkontribusi

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