Menggunakan MSAL Node dengan Linux Broker

Pustaka Autentikasi Microsoft (MSAL) Node dapat menggunakan broker Microsoft Single Sign-on untuk Linux guna menyediakan single sign-on (SSO) dan perolehan token yang aman di distribusi Linux yang didukung. Broker mengelola jabat tangan autentikasi dan siklus hidup token, memungkinkan pengguna untuk mendapatkan manfaat dari integrasi dengan akun yang diketahui oleh sistem.

Artikel ini menjelaskan apa itu broker Linux, distribusi yang didukungnya, dan cara mengaktifkan akuisisi token broker di aplikasi Node.js.

Untuk gambaran umum dukungan broker di semua platform, lihat Menggunakan MSAL Node dengan Native Token Broker.

Apa itu broker Linux

Microsoft Single Sign-On untuk Linux adalah broker autentikasi yang didistribusikan secara terpisah dari distribusi sistem Linux. Instal dengan manajer paket (sudo apt install microsoft-identity-broker atau sudo dnf install microsoft-identity-broker). Ini juga dibundel sebagai dependensi aplikasi Microsoft seperti Company Portal.

Manfaat utama meliputi:

  • Masuk tunggal. Menyederhanakan cara pengguna mengautentikasi dengan Microsoft Entra ID dan melindungi token refresh dari eksfiltrasi dan penyalahgunaan.
  • Keamanan yang ditingkatkan. Peningkatan keamanan dikirimkan melalui pembaruan broker tanpa memerlukan perubahan kode aplikasi.
  • Perlindungan token. Broker memastikan token refresh terikat perangkat.
  • Integrasi sistem. Aplikasi terhubung ke pemilih akun bawaan, memungkinkan pengguna untuk memilih akun yang ada dengan cepat.

Distribusi yang didukung

  • Ubuntu 22.04 / 24.04 (x64)
  • Red Hat Enterprise Linux (RHEL) 8 / 9 / 10 (x64)

Prasyarat

  • Node.js 18 atau yang lebih baru
  • Menginstal @azure/msal-node-extensions sebagai dependensi
  • microsoft-identity-broker harus diinstal pada perangkat
  • Daftarkan URI pengalihan broker pada pendaftaran aplikasi Anda (lihat URI Pengalihan di bawah)
  • Instal dependensi sistem yang diperlukan (lihat Dependensi sistem di bawah)

Pengalihan URI

Untuk alur broker Linux, daftarkan URI pengalihan berikut di bawah platform Aplikasi seluler dan desktop di portal Azure:

https://login.microsoftonline.com/common/oauth2/nativeclient

Ketergantungan sistem

Ubuntu 22.04/24.04

sudo apt install libsecret-1-0 libdbus-1-3
  • libsecret — Menyimpan dan mengambil token autentikasi dengan aman melalui keyring sistem (GNOME Keyring atau KDE Wallet).
  • dbus — Komunikasi antarproses dengan broker autentikasi. Bus sesi D-Bus harus berjalan (standar di lingkungan desktop; server tanpa kepala mungkin membutuhkan dbus-run-session atau setara).
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0
  • WebKitGTK — Menyediakan browser yang disematkan untuk UI masuk interaktif.
  • GTK — Toolkit UI yang mendasar yang diperlukan oleh WebKitGTK.

Aktifkan Fitur

Mengaktifkan broker Linux menggunakan konfigurasi yang sama dengan Windows dan macOS. Teruskan instance NativeBrokerPlugin dalam konfigurasi broker:

import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

Note

msal-node tidak kembali ke alur berbasis browser jika broker tidak tersedia. Hanya aktifkan autentikasi broker pada perangkat Linux yang didukung untuk menghindari kegagalan tak terduga.

Memperoleh token

Perolehan token interaktif

Gunakan acquireTokenInteractive untuk meminta token melalui broker Linux:

const tokenRequest = {
    scopes: ["User.Read"],
};

const result = await pca.acquireTokenInteractive(tokenRequest);
console.log("Access token:", result.accessToken);

Perolehan token secara diam-diam

Setelah masuk interaktif awal, permintaan token berikutnya dapat dibuat secara diam-diam:

const accounts = await pca.getAllAccounts();

if (accounts.length > 0) {
    const silentRequest = {
        scopes: ["User.Read"],
        account: accounts[0],
    };

    const result = await pca.acquireTokenSilent(silentRequest);
    console.log("Access token (silent):", result.accessToken);
}

Penyimpanan sementara token

Broker autentikasi menangani refresh dan penembolokan token akses. Token yang diperoleh melalui broker dikelola oleh broker itu sendiri dan terikat perangkat. Anda tidak perlu menyiapkan cache kustom saat menggunakan broker.

Perbedaan saat menggunakan broker Linux

  • Ketika broker perlu meminta interaksi, dialog masuk asli (berbasis WebKitGTK) muncul. Ini mengubah pengalaman pengguna (UX) dibandingkan dengan autentikasi berbasis browser.
  • Parameter forceRefresh untuk acquireTokenSilent tidak didukung. Anda mungkin menerima token yang di-cache dari broker, terlepas dari flag ini.
  • Bus sesi D-Bus harus berjalan agar komunikasi broker berfungsi.

Keterbatasan

  • Otoritas Azure AD B2C dan Layanan Federasi Direktori Aktif (AD FS) tidak didukung oleh broker Linux.
  • Penyedia identitas (IDP) pihak ketiga tidak didukung.
  • microsoft-identity-broker harus diinstal pada perangkat agar broker berfungsi.
  • msal-node tidak kembali ke browser jika broker tidak tersedia. Hanya aktifkan broker di lingkungan yang mendukungnya.
  • Bukti kepemilikan token akses (PoP) saat ini tidak didukung melalui broker Linux.
  • Last updated on