Disconnessione degli utenti

Prima di iniziare, assicurarsi di comprendere come accedere, acquisire i token e gestire la durata dei token.

Disconnessione

Il processo di disconnessione per MSAL richiede due passaggi.

1. Cancellare la cache MSAL.
2. Cancellare la sessione nel server di gestione delle identità.

L'oggetto PublicClientApplication espone due API che eseguono queste azioni.

msalInstance.logoutRedirect();
msalInstance.logoutPopup();

Queste API cancellano la cache dei token e tutti i dati utente e di sessione, quindi reindirizzano la finestra del browser o la finestra popup alla pagina di logout del server. Il server chiederà quindi all'utente di selezionare l'account da cui desidera essere disconnesso e lo reindirizzerà nuovamente a postLogoutRedirectUri, purché siano soddisfatte le condizioni seguenti:

1. L'URI viene registrato come URL di risposta nella registrazione dell'app
2. L'URI viene specificato come postLogoutRedirectUri nella configurazione PublicClientApplication oppure nella richiesta di disconnessione
3. L'utente ha una sessione attiva con il provider di identità
4. (Scenari MSA) È configurato un URL di disconnessione front-channel per la registrazione dell'app

Se una delle condizioni precedenti non viene soddisfatta, la pagina (o la finestra popup) rimarrà sulla pagina di disconnessione del provider di identità.

IMPORTANTE: Se questa procedura di disconnessione viene interrotta per qualsiasi motivo, la cache MSAL potrebbe essere svuotata, ma la sessione potrebbe ancora persistere sul server. Assicurarsi che la navigazione venga completata completamente prima di tornare all'applicazione.

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

Richiedere oggetti

Le opzioni di configurazione possono essere fornite a ognuna delle API di disconnessione per personalizzare il comportamento:

• logoutRedirect request
• logoutPopup request

logoutRedirect

L'utilizzo di logoutRedirect cancellerà la cache locale dei token dell'utente e quindi reindirizzerà la finestra alla pagina di disconnessione del server. La promessa restituita da logoutRedirect non è prevista per la risoluzione, ma è possibile attenderla se è necessario bloccare l'esecuzione di altro codice prima dell'avvio del reindirizzamento.

È possibile fornire opzioni di configurazione per personalizzare il comportamento:

const currentAccount = msalInstance.getAccount({ homeAccountId });
await msalInstance.logoutRedirect({
    account: currentAccount,
    postLogoutRedirectUri: "https://contoso.com/loggedOut"
});

Ignorare la disconnessione del server

Se si vuole che l'applicazione esegua solo la disconnessione locale, è possibile fornire un callback al onRedirectNavigate parametro nella richiesta e restituire il callback false.

msalInstance.logoutRedirect({
    onRedirectNavigate: (url) => {
        // Return false if you would like to stop navigation after local logout
        return false;
    }
});

logoutPopup

L'API logoutPopup aprirà la pagina di accesso del server in un popup, consentendo all'applicazione di mantenere lo stato corrente. A causa di questo ci sono alcune considerazioni aggiuntive su logoutRedirect quando si sceglie di usare i popup per la disconnessione:

• Si prevede che la promessa restituita da logoutPopup venga risolta dopo la chiusura del popup
• postLogoutRedirectUri è obbligatorio per consentire a MSAL di chiudere il popup al termine dell'accesso
• postLogoutRedirectUri verrà aperto nella finestra popup, non nella cornice principale. Se è necessario che l'app di primo livello venga reindirizzata dopo la disconnessione, è possibile usare il mainWindowRedirectUri parametro nella richiesta di disconnessione.

È possibile specificare le opzioni di configurazione per personalizzare il comportamento.

const currentAccount = msalInstance.getAccount({ homeAccountId });
await msalInstance.logoutPopup({
    account: currentAccount,
    postLogoutRedirectUri: "https://contoso.com/loggedOut",
    mainWindowRedirectUri: "https://contoso.com/homePage",
    popupWindowAttributes: {
        popupSize: {
            height: 100,
            width: 100
        },
        popupPosition: {
            top: 100,
            left: 100
        }
    }
});

Disconnessione senza richiesta di conferma

Se l'applicazione client ha il claim facoltativo login_hint abilitato per i token ID, è possibile sfruttare il claim login_hint del token ID per eseguire un logout "silenzioso" o senza prompt usando logoutRedirect o logoutPopup. Esistono due modi per ottenere un disconnessione senza prompt:

Opzione 1: consentire a MSAL di analizzare automaticamente il login_hint dalle attestazioni del token ID dell'account

La prima e più semplice opzione consiste nel fornire l'oggetto account per cui terminare la sessione per l'API di disconnessione. MSAL verificherà se il claim login_hint è disponibile nell'ID token dell'account e lo aggiungerà automaticamente alla richiesta di chiusura della sessione come logout_hint per ignorare il prompt di selezione dell'account.

const currentAccount = msalInstance.getAccount({ homeAccountId });
// The account's ID Token must contain the login_hint optional claim to avoid the account picker
await msalInstance.logoutRedirect({ account: currentAccount});

Opzione 2: impostare manualmente l'opzione logoutHint nella richiesta di disconnessione

In alternativa, se si preferisce impostare manualmente il logoutHint, è possibile estrarre l'attestazione login_hint nell'app e impostarla come logoutHint nella richiesta di disconnessione:

const currentAccount = msalInstance.getAccount({ homeAccountId });

// Extract login hint to use as logout hint
const logoutHint = currentAccount.idTokenClaims.login_hint;
await msalInstance.logoutPopup({ logoutHint: logoutHint });

Nota: a seconda dell'API scelta (reindirizzamento/popup), l'app continuerà a reindirizzare o aprire un popup per terminare la sessione del server. La differenza è che l'utente non visualizzerà o dovrà interagire con il prompt di selezione dell'account del server.

Disconnessione del canale anteriore

Microsoft Entra ID e Azure AD B2C supportano la funzionalità di disconnessione front-channel OAuth, che abilita l'accesso Single Sign-Out in tutte le applicazioni quando un utente avvia la disconnessione. Per sfruttare questa funzionalità con MSAL.js, seguire questa procedura:

1. Nell'applicazione creare una pagina di disconnessione dedicata. Questa pagina non deve eseguire altre funzioni, ad esempio l'acquisizione di token al caricamento della pagina (vedere di seguito per informazioni dettagliate). Si noti che questa pagina verrà caricata in un iframe nascosto e, per gli utenti Microsoft Entra ID e MSA, includerà i parametri di query iss e sid.
2. Nel Interfaccia di amministrazione di Microsoft Entra, passa alla pagina Autenticazione della tua applicazione e registra l'URL della pagina del passaggio 1 in URL di disconnessione front-channel. Si noti che questa pagina deve essere caricata tramite https.

Requisiti per la pagina di disconnessione front-channel

La pagina usata per la disconnessione front-channel deve essere compilata nel modo seguente:

1. Al caricamento della pagina richiamare automaticamente l'API MSAL logoutRedirect .
2. Nella configurazione PublicClientApplication, impostare system.allowRedirectInIframe su true.
3. Quando si richiama logout, è consigliabile impedire il reindirizzamento nell'iframe alla pagina di disconnessione (vedere sopra).

Esempio:

const msal = new PublicClientApplication({
    auth: {
        clientId: "my-client-id"
    },
    system: {
        allowRedirectInIframe: true
    }
})

// Automatically on page load
msal.logoutRedirect({
    onRedirectNavigate: () => {
        // Return false to stop navigation after local logout
        return false;
    }
});

Ora, quando un utente si disconnette da un'altra applicazione, l'URL di disconnessione del canale frontale della tua applicazione verrà caricato in un iframe nascosto e MSAL.js cancellerà la cache per completare il single sign-out.

Esempi di disconnessione del canale anteriore

Gli esempi seguenti illustrano come implementare la disconnessione front-channel usando MSAL.js:

• Esempio di MSAL Angular v2: Angular 11
• MSAL React: Esempio di router React

Eventi

Se parti diverse dell'app devono reagire allo stato di disconnessione senza accesso diretto alla promessa restituita da logoutRedirect o logoutPopup è possibile usare l'API evento.

Gli eventi verranno generati quando la disconnessione ha esito positivo o negativo e quando il popup viene aperto quando si usa logoutPopup.

Note importanti

• Se all'API di logout non viene passato alcun account o alcun oggetto EndSessionRequest, verrà effettuato il logout di tutti gli account.
• Se un account viene passato all'API di disconnessione, MSAL cancella solo i token correlati a tale account.
• L'accesso al server è una funzionalità di praticità e, di conseguenza, viene eseguita con il massimo sforzo. Le API di disconnessione verranno risolte correttamente, purché la cache dell'applicazione locale sia stata cancellata correttamente, indipendentemente dal fatto che l'accesso al server abbia esito positivo o negativo.

Operazioni successive

Esaminare argomenti più avanzati, ad esempio:

• Memorizzazione nella cache
• Opzioni di configurazione avanzate