Inisialisasi MSAL

Sebelum menginisialisasi Browser MSAL, mulailah dengan mendaftarkan aplikasi Anda di pusat admin Microsoft Entra untuk mendapatkan ID aplikasi (klien).

Pola CreatePCA

MSAL.js menyediakan pola CreatePCA yang memungkinkan Anda memilih jenis PublicClientApplication untuk aplikasi Anda. Opsi yang tersedia saat ini mencakup konfigurasi Standard dan Nestable. Di masa depan, lebih banyak konfigurasi akan diperkenalkan.

Konfigurasi Standar

Jika Anda menggunakan MSAL.js dalam aplikasi halaman tunggal, impor msal-browser untuk membuat instans IPublicClientApplication dengan createStandardPublicClientApplication. Fungsi ini membuat instans PublicClientApplication dengan konfigurasi standar.

import * as msal from "@azure/msal-browser";

const pca = msal.createStandardPublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
    },
});

Konfigurasi Aplikasi Berlapis

Jika aplikasi Anda adalah aplikasi bertingkat dalam iframe yang mendelegasikan autentikasinya ke SDK hub (yang berupa SPA atau aplikasi desktop yang berjalan dalam framework MetaOS), impor msal-browser untuk membuat instans IPublicClientApplication dengan createNestablePublicClientApplication. Fungsi ini membuat instans PublicClientApplication dengan konfigurasi NAA.

import * as msal from "@azure/msal-browser";

const nestablePca = msal.createNestablePublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
    },
});

Menginisialisasi objek PublicClientApplication

Untuk menggunakan MSAL.js, Anda perlu membuat instance objek PublicClientApplication. Anda harus menyediakan client id (appId) aplikasi Anda.

Opsi 1

Instansiasi objek PublicClientApplication dan inisialisasi setelahnya. Fungsi initialize ini asinkron dan harus diselesaikan sebelum memanggil API MSAL.js lainnya.

import { PublicClientApplication } from "@azure/msal-browser";

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = new PublicClientApplication(msalConfig);
await msalInstance.initialize();

Opsi 2

Panggil createPublicClientApplication metode statis yang mengembalikan objek yang diinisialisasi PublicClientApplication . Perhatikan bahwa fungsi ini asinkron.

import { PublicClientApplication } from "@azure/msal-browser";

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = await PublicClientApplication.createPublicClientApplication(msalConfig);

(Opsional) Konfigurasikan Otoritas

Secara bawaan, MSAL dikonfigurasi dengan tenant common, yang digunakan untuk aplikasi multitenant dan aplikasi yang mengizinkan akun pribadi (bukan B2C).

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/common/'
    }
};

Jika audiens aplikasi Anda adalah penyewa tunggal, Anda harus memberikan otoritas dengan id penyewa Anda seperti di bawah ini:

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/{your_tenant_id}'
    }
};

Jika aplikasi Anda menggunakan otoritas terpisah yang sesuai dengan OIDC seperti "https://login.live.com" atau IdentityServer, Anda perlu memberikannya dalam bidang knownAuthorities dan menyetel protocolMode Anda ke "OIDC".

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.live.com',
        knownAuthorities: ["login.live.com"],
    },
    system: {
        protocolMode: "OIDC",
    }
};

(Opsional) Konfigurasikan URI Pengalihan

Secara bawaan, MSAL dikonfigurasi untuk menetapkan URI pengalihan ke halaman saat ini tempat MSAL sedang berjalan. Jika Anda ingin menerima kode otorisasi di halaman yang berbeda dari yang menjalankan MSAL, Anda dapat mengaturnya dalam konfigurasi:

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/{your_tenant_id}',
        redirectUri: 'https://contoso.com'
    }
};

Setiap URI pengalihan yang digunakan harus dikonfigurasi dalam pendaftaran portal. Anda juga dapat mengatur URI pengalihan per permintaan menggunakan API login dan permintaan.

(Opsional) Konfigurasi Tambahan

MSAL memiliki opsi konfigurasi tambahan yang dapat Anda tinjau di sini.

Menangani Peluncuran Aplikasi dengan 0 Akun atau Lebih yang Tersedia

Diagram alur berikut dapat membantu Anda menghindari permintaan autentikasi yang tidak perlu saat akun (atau beberapa akun) tersedia untuk SSO.

Memilih Jenis Interaksi

Di browser, ada dua cara untuk menyajikan layar masuk kepada pengguna dari aplikasi Anda:

• menyajikan jendela popup dari halaman saat ini
• mengalihkan jendela browser ke server masuk

API Popup

• loginPopup
• acquireTokenPopup

API popup menggunakan Promise ES6 yang akan diselesaikan saat alur autentikasi di popup selesai dan kembali ke URI pengalihan yang ditentukan, atau akan ditolak jika ada masalah pada kode atau popup diblokir.

Pertimbangan RedirectUri

Saat menggunakan API popup, redirectUri harus menunjuk ke halaman khusus yang mengimplementasikan jembatan pengalihan MSAL. Halaman ini menangani respons autentikasi dan mengkomunikasikannya kembali ke aplikasi utama.

Untuk panduan terperinci tentang menyiapkan halaman pengalihan, lihat Pertimbangan RedirectUri.

msalInstance.loginPopup({
    redirectUri: "http://localhost:3000/redirect",
});

Mengalihkan API

• loginRedirect
• acquireTokenRedirect

Catatan: Jika Anda menggunakan msal-angular atau msal-react, pengalihan ditangani secara berbeda, dan Anda akan melihat msal-angular dokumen pengalihan dan msal-react FAQ untuk detail selengkapnya.

API pengalihan merupakan fungsi asinkron (yaitu, mengembalikan promise) void yang mengalihkan jendela browser setelah menyimpan beberapa informasi dasar dalam cache. Jika Anda memilih untuk menggunakan API pengalihan, ketahuilah bahwa Anda HARUS memanggil handleRedirectPromise() untuk menangani API dengan benar. Anda dapat menggunakan fungsi berikut untuk melakukan tindakan ketika pertukaran token ini selesai:

msalInstance.handleRedirectPromise().then((tokenResponse) => {
    // Check if the tokenResponse is null
    // If the tokenResponse !== null, then you are coming back from a successful authentication redirect.
    // If the tokenResponse === null, you are not coming back from an auth redirect.
}).catch((error) => {
    // handle error, either in the library or coming back from the server
});

Ini juga akan memungkinkan Anda untuk mengambil token pada pemuatan ulang halaman. Lihat sampel onPageLoad untuk informasi selengkapnya tentang penggunaan.

Tidak disarankan untuk menggunakan kedua jenis interaksi dalam satu aplikasi.

Langkah Selanjutnya

Anda siap untuk melakukan login!