Account nel browser MSAL

Questa è la documentazione relativa agli account specifici della piattaforma per la @azure/msal-browser libreria, che fornisce le API seguenti per accedere agli account memorizzati nella cache:

• getAllAccounts(): restituisce tutti gli account attualmente presenti nella cache. Supporta un filtro facoltativo per restituire un set specifico di account. Un'applicazione deve scegliere un account per acquisire i token in modo invisibile all'utente.
• getAccount(): restituisce il primo account memorizzato nella cache corrispondente al filtro passato. L'ordine in cui gli account vengono letti dalla cache è arbitrario e non esiste alcuna garanzia che il primo account nell'elenco filtrato sarà lo stesso per due chiamate di getAccount. Come illustrato di seguito, l'aumento del numero di attributi di filtro fornirà corrispondenze più esatte.

Oggetto Filtro account

La documentazione del tipo AccountFilter elenca le proprietà che possono essere usate e combinate per filtrare gli account.

Le API seguenti getAccountBy sono state deprecate. getAccount() Usare invece con un oggetto filtro appropriato:

• getAccountByHomeId(): usare getAccount({ homeAccountId }) invece .
• getAccountByLocalId(): usare getAccount({ localAccountId }) invece .
• getAccountByUsername(): usare getAccount({ username }) invece .

Di seguito sono riportati esempi di utilizzo che illustrano queste API:

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
        }
    }
}

Ora, le proprietà dell'account, ad esempio , homeAccountIdlocalAccountIde username possono essere usate per cercare l'account memorizzato nella cache prima di acquisire un token in modo invisibile all'utente:

// 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);
    });
}

Filtro in base all'hint di accesso

A partire da , tutti i valori degli hint di @azure/msal-browser@3.2.0accesso possono essere usati per cercare e filtrare gli account. Per filtrare in base all'hint di accesso, MSAL confronta il loginHint valore nell'oggetto con gli attributi dell'account AccountFilter seguenti (in ordine di precedenza) per cercare corrispondenze:

• login_hint Attestazione del token ID
• username proprietà account
• upn Attestazione del token ID

Uso dell'attestazione login_hint

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);
});

Uso di 'username''

Passaggio username come 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);
});

Passaggio username come 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);
});

Uso dell'attestazione upn

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 dell'account attivo

La @azure/msal-browser libreria offre anche 2 API utili per tenere traccia dell'account attualmente "attivo" e deve essere usato per le richieste di token.

• getActiveAccount(): restituisce l'account attivo corrente
• setActiveAccount(): riceve un oggetto account e lo imposta come account attivo

La scelta dell'account da usare per acquisire i token dipende dall'app, tuttavia, dopo aver determinato quale account si vuole usare, è sufficiente chiamare l'API setActiveAccount() con l'oggetto account scelto. Tutte acquireTokenle chiamate o loginssoSilent useranno ora l'account attivo per impostazione predefinita se non è specificato un account diverso nella singola richiesta. Per cancellare l'account attualmente attivo, è possibile chiamare 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"] });
}

Nota: a partire dalla versione 2.16.0 l'account attivo viene archiviato nel percorso della cache configurato nell'istanza PublicClientApplication . Se si usa una versione precedente, l'account attivo viene archiviato in memoria e pertanto deve essere reimpostato in ogni caricamento della pagina.

Autenticazione dell'app annidata

Per le applicazioni setActiveAccount() NAA e getActiveAccount() sono NO-OP API. Anche se gli utenti possono impostare e ottenere account attivi, vengono ignorati attivamente poiché l'applicazione NAA deve avere sempre un account e l'account viene fornito dall'applicazione host con accountContext. In futuro, quando più account sono supportati negli hub, si prevede che questo comportamento cambi.

Note

• L'esempio predefinito msal-browser corrente presenta uno scenario con account singolo funzionante.
• Se si ha più account, modificare l'esempio (in handleResponse()) per elencare tutti gli account memorizzati nella cache e scegliere un account specifico.
• Se un'applicazione vuole recuperare un account in usernamebase a , deve salvare username (dalla risposta di un'API login per un utente specifico) prima di usare il username filtro nell'API getAccount() .
• getAllAccounts() restituisce più account se sono state effettuate diverse richieste di token interattivo e l'utente ha selezionato account diversi in due o più di tali interazioni. Potrebbe essere necessario passare prompt: "select_account" o prompt: "login" all'API acquireToken interattiva o di accesso per Microsoft Entra ID visualizzare la schermata di selezione dell'account dopo la prima interazione.
• Le API account restituiscono lo stato dell'account locale e non riflettono necessariamente lo stato del server. Restituiscono account che in precedenza hanno eseguito l'accesso a questa app usando MSAL.js e la sessione del server potrebbe essere attiva o meno.
• Due app ospitate in domini diversi non condividono lo stato dell'account a causa del fatto che l'archiviazione del browser viene segementata dal dominio.
• getAllAccounts() non è ordinato e non è garantito che sia nello stesso ordine tra più chiamate
• Ogni chiamata riuscita a un'API acquireToken o di accesso restituirà esattamente un account