Menggunakan MSAL Node dengan Native Token Broker (Windows)

Pustaka Autentikasi Microsoft (MSAL) Node mendukung perolehan token dari broker token asli. Saat menggunakan broker asli, token refresh terikat ke perangkat tempat mereka diperoleh dan tidak dapat diakses oleh msal-node atau aplikasi. Ini memberikan tingkat keamanan yang lebih tinggi yang tidak dapat dicapai sendiri msal-node .

Artikel ini menjelaskan cara mengonfigurasi broker Windows, menyiapkan bukti kepemilikan, dan memahami perilaku khusus broker.

Dukungan broker tersedia di platform berikut:

Apa itu broker

Broker autentikasi adalah komponen yang berjalan pada komputer pengguna dan mengelola jabat tangan autentikasi dan siklus hidup token untuk akun yang terhubung. Pada Windows, peran ini dilakukan oleh Web Account Manager (WAM). Manfaat utama meliputi:

• Keamanan yang ditingkatkan. Peningkatan keamanan dikirimkan melalui pembaruan OS atau broker tanpa memerlukan perubahan kode aplikasi. Token refresh terikat perangkat dan dilindungi dari eksfiltrasi.
• Dukungan fitur. Akses ke kemampuan OS yang kaya seperti Windows Hello, kebijakan Akses Bersyarat Microsoft Entra, dan kunci keamanan Fast Identity Online (FIDO) tanpa kode perancah tambahan.
• Integrasi sistem. Aplikasi terhubung ke pemilih akun bawaan, memungkinkan pengguna untuk dengan cepat memilih akun yang ada alih-alih memasukkan kembali kredensial.
• Perlindungan token. Broker memastikan token refresh terikat perangkat dan memungkinkan aplikasi memperoleh token akses bukti kepemilikan.

Arsitektur yang didukung

• Windows: x64, x86, ARM64

Prasyarat

• Node.js 18 atau yang lebih baru
• Menginstal @azure/msal-node-extensions sebagai dependensi
• Daftarkan URI pengalihan broker pada pendaftaran aplikasi Anda. Untuk nilai yang diperlukan, lihat Mengalihkan URI.

Pengalihan URI

Daftarkan URI pengalihan berikut di bawah platform Aplikasi seluler dan desktop di portal Azure:

ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>

Ganti <your-client-id> dengan ID klien aplikasi Anda.

Aktifkan Fitur

Mengaktifkan broker token hanya memerlukan satu parameter konfigurasi. 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);

Contoh yang berfungsi dapat ditemukan di sampel auth-code-cli-brokered-app.

Induk jendela

Agar perintah autentikasi ditampilkan melalui aplikasi panggilan dan memblokir interaksi lebih lanjut, berikan handel jendela aplikasi ke acquireTokenInteractive API.

Untuk aplikasi CLI, upaya terbaik untuk menemukan handel jendela dilakukan di bawah tenda, tetapi tidak dapat diandalkan.

Jika Anda menggunakan Electron, gunakan getNativeWindowHandle API dan teruskan hasilnya ke :acquireTokenInteractive

import { BrowserWindow } from "electron";

const win = new BrowserWindow();
const pca = new PublicClientApplication(msalConfig);

pca.acquireTokenInteractive({
    windowHandle: win.getNativeWindowHandle(),
});

Bukti kepemilikan

Bukti kepemilikan token akses (PoP) didukung saat memperoleh token melalui broker asli. Untuk meminta token PoP, tambahkan properti berikut ke objek permintaan yang disediakan ke acquireTokenInteractive atau acquireTokenSilent:

Parameter permintaan AT PoP

Contoh penggunaan

Contoh ini meminta token bukti kepemilikan dengan mengatur skema autentikasi dan properti permintaan HTTP yang ditandatangani:

import { PublicClientApplication, Configuration, AuthenticationScheme } 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);

const popTokenRequest = {
    scopes: ["User.Read"],
    authenticationScheme: AuthenticationScheme.POP,
    resourceRequestMethod: "POST",
    resourceRequestUri: "YOUR_RESOURCE_ENDPOINT",
    shrNonce: "NONCE_ACQUIRED_FROM_RESOURCE_SERVER",
};

pca.acquireTokenInteractive(popTokenRequest);
pca.acquireTokenSilent(popTokenRequest);

Perbedaan saat menggunakan broker Windows

Ada beberapa hal yang mungkin berperilaku berbeda ketika memperoleh token melalui broker asli:

• Parameter forceRefresh untuk acquireTokenSilent panggilan tidak didukung. Anda mungkin menerima token yang di-cache dari broker, apa pun nilai yang ditetapkan untuk flag ini.
• Jika broker perlu meminta pengguna untuk berinteraksi, prompt sistem akan muncul. Ini mengubah pengalaman pengguna (UX) karena autentikasi tidak terjadi di jendela browser.
• Bukti kepemilikan atas token akses didukung oleh broker, tetapi tidak didukung oleh alur tanpa broker.