Akun di Browser MSAL

Ini adalah dokumentasi Akun khusus platform untuk @azure/msal-browser pustaka, yang menyediakan API berikut untuk mengakses akun cache:

  • getAllAccounts(): mengembalikan semua akun yang saat ini ada di cache. Mendukung filter opsional untuk mengembalikan sekumpulan akun tertentu. Aplikasi harus memilih akun untuk memperoleh token secara diam-diam.
  • getAccount(): mengembalikan akun cache pertama yang cocok dengan filter yang diteruskan. Urutan di mana akun dibaca dari cache bersifat arbitrer dan tidak ada jaminan bahwa akun pertama dalam daftar yang difilter akan sama untuk dua panggilan getAccount. Seperti yang dijelaskan di bawah ini, meningkatkan jumlah atribut filter akan memberikan kecocokan yang lebih tepat.

Objek Filter Akun

Dokumentasi jenis AccountFilter mencantumkan properti yang dapat digunakan dan digabungkan untuk memfilter akun.

Note

Atribut filter akun tunggal biasanya tidak dijamin untuk mengidentifikasi objek akun yang di-cache secara unik. Menambahkan kombinasi atribut yang tidak diulang bersama-sama, seperti homeAccountId + localAccountId, dapat membantu menyempurnakan pencarian.

Note

realm berada tenantId di cache.

API berikut getAccountBy tidak digunakan lagi. Silakan gunakan getAccount() dengan objek filter yang sesuai sebagai gantinya:

  • getAccountByHomeId(): gunakan getAccount({ homeAccountId }) sebagai gantinya.
  • getAccountByLocalId(): gunakan getAccount({ localAccountId }) sebagai gantinya.
  • getAccountByUsername(): gunakan getAccount({ username }) sebagai gantinya.

Berikut ini adalah contoh penggunaan yang mencakup API ini:


let homeAccountId = null; // Initialize global accountId (can also be localAccountId or username) used for account lookup later, ideally stored in app state

// This callback is passed into `acquireTokenPopup` and `acquireTokenRedirect` to handle the interactive auth response
function handleResponse(resp) {
    if (resp !== null) {
        homeAccountId = resp.account.homeAccountId; // alternatively: resp.account.homeAccountId or resp.account.username
    } else {
        const currentAccounts = myMSALObj.getAllAccounts();
        if (currentAccounts.length < 1) { // No cached accounts
            return;
        } else if (currentAccounts.length > 1) { // Multiple account scenario
            // Add account selection code here
            homeAccountId = ...
        } else if (currentAccounts.length === 1) {
            homeAccountId = currentAccounts[0].homeAccountId; // Single account scenario
        }
    }
}

Sekarang, properti akun seperti: homeAccountId, localAccountId, dan username dapat digunakan untuk mencari akun cache sebelum memperoleh token secara diam-diam:

// This method attempts silent token acquisition and falls back on acquireTokenPopup
async function getTokenPopup(request, homeAccountId) {
    // In this case, accounts are filtered by homeAccountId, but more attributes can be added to refine the search and increase the precision of the account filter
    const accountFilter = {
        homeAccountId: homeAccountId,
    };
    request.account = myMSALObj.getAccount(accountFilter);
    return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
        // Handle error
        return await myMSALObj.acquireTokenPopup(request);
    });
}

Pemfilteran menurut petunjuk masuk

@azure/msal-browser@3.2.0Pada , semua nilai petunjuk masuk dapat digunakan untuk mencari dan memfilter akun. Untuk memfilter menurut petunjuk masuk, MSAL akan membandingkan loginHint nilai dalam AccountFilter objek dengan atribut akun berikut (dalam urutan prioritas) untuk mencari kecocokan:

  • login_hint Klaim token ID
  • username properti akun
  • upn Klaim token ID

Note

Semua atribut di atas dapat diteruskan ke filter akun sebagai loginHint properti . Filter akun juga akan menerima username atribut sebagai username, dan akan menghasilkan pencarian yang lebih berkinerja.

Menggunakan login_hint klaim

const accountFilter = {
    loginHint: previouslyObtainedIdTokenClaims.login_hint;
};
request.account = myMSALObj.getAccount(accountFilter);
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
    // Handle error
    return await myMSALObj.acquireTokenPopup(request);
});

Menggunakan 'nama pengguna''

Note

Nilai username dapat disertakan AccountFilter dalam objek sebagai username atau loginHint. Ini karena username klaim adalah salah satu dari 3 nilai (bersama dengan login_hint klaim token ID dan upn ) yang diterima layanan token sebagai petunjuk masuk. Jika aplikasi Anda yakin bahwa nilai yang dimaksud adalah username, mengaturnya karena AccountFilter.username properti akan menghasilkan performa pencarian yang lebih baik. Mampu menetapkan username nilai sebagaimana loginHint berguna jika aplikasi Anda menggunakan petunjuk masuk dan tidak menyimpan konteks tentang apakah nilai tersebut berasal dari usernameklaim , , login_hintatau upn .

Meneruskan username sebagai loginHint

const accountUsername = userProfile.username;
const accountFilter = {
    loginHint: accountUsername;
};
request.account = myMSALObj.getAccount(accountFilter);
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
    // Handle error
    return await myMSALObj.acquireTokenPopup(request);
});

Meneruskan username sebagai username

const accountUsername = userProfile.username;
const accountFilter = {
    username: accountUsername;
};
request.account = myMSALObj.getAccount(accountFilter);
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
    // Handle error
    return await myMSALObj.acquireTokenPopup(request);
});

Menggunakan upn klaim

const accountFilter = {
    loginHint: previouslyObtainedIdTokenClaims.upn;
};
request.account = myMSALObj.getAccount(accountFilter);
return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
    // Handle error
    return await myMSALObj.acquireTokenPopup(request);
});

API Akun Aktif

@azure/msal-browser Pustaka juga menyediakan 2 API yang nyaman untuk membantu Anda melacak akun mana yang saat ini "aktif" dan harus digunakan untuk permintaan token.

  • getActiveAccount(): Mengembalikan akun aktif saat ini
  • setActiveAccount(): Menerima objek akun dan menetapkannya sebagai akun aktif

Memutuskan akun mana yang akan digunakan untuk memperoleh token tergantung pada aplikasi, namun, setelah Anda menentukan akun mana yang ingin Anda gunakan, cukup panggil setActiveAccount() API dengan objek akun yang dipilih. Setiap acquireTokenpanggilan , login atau ssoSilent sekarang akan menggunakan akun aktif secara default jika akun yang berbeda tidak ditentukan dalam permintaan individual. Untuk menghapus akun aktif saat ini, Anda dapat memanggil setActiveAccount(null).

function login() {
    return myMsalObj.loginPopup().then((response) => {
        // After a successful login set the active account to be the user that just logged in
        myMsalObj.setActiveAccount(response.account);
    });
}

function getAccessToken() {
    // Providing an account in the token request is not required if there is an active account set
    return myMsalObj.acquireTokenSilent({ scopes: ["User.Read"] });
}

Catatan: Pada versi 2.16.0, akun aktif disimpan di lokasi cache yang dikonfigurasi pada instans Anda PublicClientApplication . Jika Anda menggunakan versi sebelumnya, akun aktif disimpan dalam memori dan dengan demikian harus diatur ulang pada setiap pemuatan halaman.

Autentikasi Aplikasi Berlapis

Untuk aplikasi NAA, setActiveAccount() dan getActiveAccount() merupakan API NO-OP. Meskipun pengguna dapat mengatur dan mendapatkan akun aktif, mereka secara aktif diabaikan karena aplikasi NAA selalu diharapkan memiliki satu akun dan akun disediakan oleh aplikasi host dengan accountContext. Di masa mendatang ketika beberapa akun didukung di seluruh hub, perilaku ini diharapkan berubah.

Notes

  • Sampel default msal-browser saat ini memiliki skenario akun tunggal yang berfungsi.
  • Jika Anda memiliki beberapa skenario akun, ubah sampel (dalam handleResponse()) untuk mencantumkan semua akun yang di-cache dan pilih akun tertentu.
  • Jika aplikasi ingin mengambil akun berdasarkan username, aplikasi perlu menyimpan username (dari respons login API untuk pengguna tertentu) sebelum menggunakan username filter di getAccount() API.
  • getAllAccounts() akan mengembalikan beberapa akun jika Anda telah membuat beberapa permintaan token interaktif dan pengguna telah memilih akun yang berbeda dalam dua atau beberapa interaksi tersebut. Anda mungkin perlu meneruskan prompt: "select_account" atau prompt: "login" ke acquireToken interaktif atau API masuk agar Microsoft Entra ID menampilkan layar pemilihan akun setelah interaksi pertama.
  • API akun mengembalikan status akun lokal dan tidak selalu mencerminkan status server. Mereka mengembalikan akun yang sebelumnya telah masuk ke aplikasi ini menggunakan MSAL.js dan sesi server mungkin atau mungkin masih belum aktif.
  • Dua aplikasi yang dihosting di domain yang berbeda tidak berbagi status akun karena penyimpanan browser dipisahkan oleh domain.
  • getAllAccounts() tidak diurutkan dan tidak dijamin berada dalam urutan yang sama di beberapa panggilan
  • Setiap panggilan yang berhasil ke acquireToken atau API login akan mengembalikan tepat satu akun
  • Last updated on