Masuk tunggal dengan MSAL.js

Akses menyeluruh (SSO) memberikan pengalaman yang lebih mulus dengan mengurangi berapa kali pengguna dimintai kredensial. Pengguna memasukkan kredensial mereka sekali, dan sesi yang ditetapkan dapat digunakan kembali oleh aplikasi lain pada perangkat yang sama tanpa meminta lebih lanjut.

Microsoft Entra ID mengaktifkan SSO dengan mengatur cookie sesi saat pengguna mengautentikasi untuk pertama kalinya. MSAL.js juga menyimpan token ID dan token akses pengguna di penyimpanan browser per domain aplikasi. Kedua mekanisme tersebut, cookie sesi Microsoft Entra dan cache Pustaka Autentikasi Microsoft (MSAL), tidak bergantung satu sama lain tetapi bekerja bersama untuk menyediakan fungsionalitas SSO.

SSO antar tab browser untuk aplikasi yang sama

Ketika pengguna membuka aplikasi di beberapa tab dan masuk di salah satunya, mereka dapat masuk ke aplikasi yang sama yang terbuka di tab lain tanpa diminta. Untuk melakukannya, Anda perlu mengatur cacheLocation di objek konfigurasi MSAL.js ke localStorage seperti yang ditunjukkan dalam contoh berikut:

const config = {
  auth: {
    clientId: "1111-2222-3333-4444-55555555",
  },
  cache: {
    cacheLocation: "localStorage",
  },
};

const msalInstance = new msal.PublicClientApplication(config);

Dalam hal ini, instans aplikasi di tab browser yang berbeda menggunakan cache MSAL yang sama, sehingga berbagi status autentikasi di antara mereka. Anda juga dapat menggunakan peristiwa MSAL untuk memperbarui instans aplikasi saat pengguna masuk dari tab atau jendela browser lain. Untuk informasi selengkapnya, lihat: Menyinkronkan log masuk status di seluruh tab dan jendela

SSO antara aplikasi yang berbeda

Saat pengguna mengautentikasi, cookie sesi diatur pada domain Microsoft Entra di browser. MSAL.js bergantung pada cookie sesi ini untuk menyediakan SSO bagi pengguna di antara aplikasi yang berbeda. Secara khusus, MSAL.js menyediakan metode ssoSilent untuk mengautentikasi pengguna dan memperoleh token tanpa interaksi pengguna. Namun, jika pengguna memiliki beberapa akun pengguna dalam sesi dengan Microsoft Entra ID, mereka kemudian diminta untuk memilih akun untuk masuk. Dengan demikian, ada dua cara untuk mencapai SSO menggunakan ssoSilent metode .

Dengan petunjuk untuk pengguna

Untuk meningkatkan performa dan memastikan bahwa server otorisasi akan mencari sesi akun yang benar, Anda dapat meneruskan salah satu opsi berikut dalam objek ssoSilent permintaan metode untuk mendapatkan token secara diam-diam.

login_hint, yang dapat diambil dari properti nama pengguna objek account atau klaim upn dalam token ID. Jika aplikasi Anda mengautentikasi pengguna dengan B2C, lihat: Mengonfigurasi alur pengguna B2C untuk memancarkan nama pengguna dalam token ID
ID Sesi, sid, yang dapat diambil dari idTokenClaims objek account.
account, yang dapat diambil melalui salah satu metode akun

Kami merekomendasikan penggunaan login_hintklaim opsional token ID yang diberikan ke ssoSilent sebagai loginHint, karena ini merupakan petunjuk akun yang paling andal untuk permintaan senyap maupun interaktif.

Klaim login_hint opsional memberikan petunjuk untuk Microsoft Entra ID tentang akun pengguna yang mencoba masuk. Untuk melewati prompt pemilihan akun yang biasanya ditampilkan selama permintaan autentikasi interaktif, berikan loginHint seperti yang ditunjukkan berikut:

const silentRequest = {
    scopes: ["User.Read", "Mail.Read"],
    loginHint: "user@contoso.com"
};

try {
    const loginResponse = await msalInstance.ssoSilent(silentRequest);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(silentRequest).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Dalam contoh ini, loginHint berisi email pengguna atau UPN, yang digunakan sebagai petunjuk selama permintaan token interaktif. Petunjuk dapat diteruskan antara aplikasi untuk memfasilitasi SSO senyap, di mana aplikasi A dapat memasukkan pengguna, membaca loginHint, dan kemudian mengirim klaim dan konteks penyewa saat ini ke aplikasi B. Microsoft Entra ID akan mencoba mengisi formulir masuk sebelumnya atau melewati perintah pemilihan akun dan langsung melanjutkan dengan proses autentikasi untuk pengguna yang ditentukan.

Jika informasi dalam klaim login_hint tidak cocok dengan pengguna mana pun yang sudah ada, pengguna akan diarahkan ke proses masuk standar, termasuk pemilihan akun.

Menggunakan ID sesi

Untuk menggunakan ID sesi, tambahkan sid sebagai klaim opsional ke token ID aplikasi Anda. Klaim ini sid memungkinkan aplikasi mengidentifikasi sesi Microsoft Entra pengguna terlepas dari nama akun atau nama pengguna mereka. Untuk mempelajari cara menambahkan klaim opsional seperti sid, lihat Memberikan klaim opsional ke aplikasi Anda. Gunakan ID sesi (SID) dalam permintaan autentikasi senyap yang Anda buat menggunakan ssoSilent di MSAL.js.

const request = {
  scopes: ["user.read"],
  sid: sid,
};

 try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Menggunakan objek akun

Jika Anda mengetahui informasi akun pengguna, Anda juga dapat mengambil akun pengguna menggunakan metode getAccountByUsername() atau getAccountByHomeId():

const username = "test@contoso.com";
const myAccount  = msalInstance.getAccountByUsername(username);

const request = {
    scopes: ["User.Read"],
    account: myAccount
};

try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Tanpa petunjuk dari pengguna

Anda dapat mencoba menggunakan metode ssoSilent tanpa meneruskan parameter account, sid, atau login_hint seperti yang ditunjukkan pada kode berikut:

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

try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Namun, ada kemungkinan terjadi kesalahan saat masuk secara senyap jika aplikasi digunakan oleh beberapa pengguna dalam satu sesi browser atau jika pengguna memiliki beberapa akun dalam sesi browser yang sama. Kesalahan berikut dapat ditampilkan jika beberapa akun tersedia:

InteractionRequiredAuthError: interaction_required: AADSTS16000: Either multiple user identities are available for the current request or selected account is not supported for the scenario.

Kesalahan menunjukkan bahwa server tidak dapat menentukan akun mana yang akan masuk, dan akan memerlukan salah satu parameter dalam contoh sebelumnya (account, , login_hintsid) atau masuk interaktif untuk memilih akun.

Pertimbangan saat menggunakan `ssoSilent`

URI pengalihan (URL balasan)

Untuk performa yang lebih baik dan untuk membantu menghindari masalah, atur redirectUri ke halaman kosong atau halaman lain yang tidak menggunakan MSAL.

Jika pengguna aplikasi hanya menggunakan metode pop-up dan senyap, atur redirectUri pada objek konfigurasi PublicClientApplication.
Jika aplikasi juga menggunakan metode pengalihan, atur redirectUri berdasarkan per permintaan.

Cookie pihak ketiga

ssoSilent mencoba membuka iframe tersembunyi dan menggunakan kembali sesi yang ada dengan Microsoft Entra ID. Ini tidak akan berfungsi di browser yang memblokir cookie pihak ketiga seperti Safari, dan akan menyebabkan kesalahan interaksi:

InteractionRequiredAuthError: login_required: AADSTS50058: A silent sign-in request was sent but no user is signed in. The cookies used to represent the user's session were not sent in the request to Azure AD

Untuk mengatasi kesalahan, pengguna harus membuat permintaan autentikasi interaktif menggunakan loginPopup() atau loginRedirect(). Dalam beberapa kasus, nilai prompt none dapat digunakan bersama dengan metode interaktif MSAL.js untuk mewujudkan SSO. Lihat Permintaan interaktif dengan prompt=none untuk informasi selengkapnya. Jika Anda sudah memiliki informasi login pengguna, Anda dapat meneruskan salah satu parameter opsional loginHint atau sid untuk login ke akun tertentu.

Meniadakan SSO dengan prompt=login

Jika Anda lebih suka Microsoft Entra ID meminta pengguna untuk memasukkan kredensial mereka meskipun sesi aktif dengan server otorisasi, Anda dapat menggunakan parameter permintaan masuk dalam permintaan dengan MSAL.js. Lihat perilaku permintaanMSAL.js untuk informasi selengkapnya.

MSAL.js menghadirkan paritas fitur dengan ADAL.js untuk skenario autentikasi Microsoft Entra. Untuk membuat migrasi dari ADAL.js ke MSAL.js mudah dan berbagi status autentikasi antar aplikasi, pustaka membaca token ID yang mewakili sesi pengguna di cache ADAL.js. Untuk memanfaatkan ini saat bermigrasi dari ADAL.js, Anda harus memastikan bahwa pustaka menggunakan localStorage untuk cache token. Atur cacheLocation ke localStorage dalam konfigurasi MSAL.js dan ADAL.js pada inisialisasi sebagai berikut:


// In ADAL.js
window.config = {
  clientId: "1111-2222-3333-4444-55555555",
  cacheLocation: "localStorage",
};

var authContext = new AuthenticationContext(config);

// In latest MSAL.js version
const config = {
  auth: {
    clientId: "1111-2222-3333-4444-55555555",
  },
  cache: {
    cacheLocation: "localStorage",
  },
};

const msalInstance = new msal.PublicClientApplication(config);

Langkah berikutnya

Untuk informasi selengkapnya tentang SSO, lihat:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-02