Menggunakan MSAL Node dengan macOS Broker

Pustaka Autentikasi Microsoft (MSAL) Node dapat menggunakan broker autentikasi macOS untuk menyediakan akses menyeluruh (SSO) dan akuisisi token aman dengan menggunakan akun yang diketahui oleh sistem operasi. Artikel ini menjelaskan broker macOS dan cara mengaktifkan dan menggunakan autentikasi broker di MSAL Node.

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

Apa itu broker macOS

Di macOS, broker autentikasi disediakan oleh plug-in SSO Perusahaan Microsoft untuk perangkat Apple, yang dikirim dengan aplikasi Company Portal. Broker mengelola jabat tangan autentikasi dan siklus hidup token untuk akun yang terhubung. Manfaat utama meliputi:

• Keamanan yang ditingkatkan. Peningkatan keamanan dikirimkan melalui pembaruan broker tanpa memerlukan perubahan kode aplikasi. Token refresh terikat perangkat dan dilindungi dari eksfiltrasi.
• Integrasi sistem. Pengguna dapat menggunakan kembali akun masuk yang ada dari Company Portal, mengurangi entri ulang kredensial.
• Perlindungan token. Broker memastikan token refresh terikat ke konteks perangkat.

Platform dan arsitektur yang didukung

Komponen	Dukungan
Arsitektur	ARM64 (Apple Silicon) dan x64 (Intel)
Versi macOS	macOS 10.15 (Catalina) dan yang lebih baru

Tip

Sebaiknya perbarui ke versi macOS terbaru untuk memastikan kompatibilitas dengan fitur keamanan terbaru dan kemampuan broker.

Prasyarat

• Node.js 18 atau yang lebih baru
• Menginstal @azure/msal-node-extensions sebagai dependensi
• Perangkat harus didaftarkan melalui Company Portal. Setelah pendaftaran, verifikasi bahwa aplikasi Microsoft lain dapat masuk melalui ekstensi SSO (misalnya, Anda dapat masuk ke Word melalui Company Portal).
• Daftarkan URI pengalihan broker pada pendaftaran aplikasi Anda. Untuk nilai URI yang didukung, lihat Mengalihkan URI.

Pengalihan URI

Untuk alur broker macOS, Anda harus mendaftarkan URI pengalihan khusus platform di bawah platform Aplikasi seluler dan desktop di portal Azure.

Untuk aplikasi yang tidak ditandatangani (skrip, alat CLI):

Gunakan URI pengalihan berikut untuk aplikasi yang tidak ditandatangani, seperti skrip dan alat CLI:

msauth.com.msauth.unsignedapp://auth

Untuk aplikasi yang ditandatangani/dibundel:

Gunakan format URI pengalihan berikut untuk aplikasi yang ditandatangani atau dibundel:

msauth.<your-bundle-id>://auth

Ganti <your-bundle-id> dengan pengidentifikasi bundel Apple aplikasi Anda (misalnya, msauth.com.example.myapp://auth).

Important

URI pengalihan broker sebaiknya hanya digunakan untuk alur broker. Jika aplikasi Anda juga menggunakan alur autentikasi berbasis browser, gunakan URI pengalihan terpisah untuk alur tersebut. Memberikan URI pengalihan broker ke alur yang berbasis browser akan menyebabkan kesalahan.

Aktifkan Fitur

Mengaktifkan broker macOS memerlukan konfigurasi yang sama dengan Windows. 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 di lingkungan yang mendukung broker untuk menghindari kegagalan tak terduga.

Memperoleh token

Perolehan token interaktif

Gunakan acquireTokenInteractive untuk meminta token melalui broker macOS:

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 mengonfigurasi cache kustom saat menggunakan broker.

Perbedaan saat menggunakan broker macOS

• Ketika broker perlu meminta interaksi, dialog autentikasi macOS asli 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.
• Bukti kepemilikan token akses (PoP) didukung melalui broker.

Keterbatasan

• Otoritas Azure AD B2C dan Layanan Federasi Direktori Aktif (AD FS) tidak didukung melalui broker di macOS.
• Penyedia identitas (IDP) pihak ketiga tidak didukung.
• Company Portal harus diinstal dan perangkat harus terdaftar agar broker berfungsi.
• msal-node tidak kembali ke browser jika broker tidak tersedia. Hanya aktifkan broker di lingkungan yang mendukungnya.