Gestire errori ed eccezioni in MSAL.js

Questo articolo presenta una panoramica dei diversi tipi di errori e fornisce raccomandazioni per la gestione degli errori di accesso comuni.

Informazioni di base sulla gestione degli errori di MSAL

Le eccezioni in Microsoft Authentication Library (MSAL) sono destinate agli sviluppatori di app per la risoluzione dei problemi, non per essere visualizzate dagli utenti finali. I messaggi di eccezione non sono localizzati.

Durante l'elaborazione di eccezioni ed errori, è possibile usare il tipo di eccezione e il codice di errore per distinguere le eccezioni. Per un elenco dei codici di errore, vedere Codici di errore di autenticazione e autorizzazione di Microsoft Entra.

Durante l'esperienza di accesso, è possibile che si verifichino errori relativi a consenso, accesso condizionale (autenticazione a più fattori, gestione dei dispositivi, restrizioni basate sulla posizione), rilascio e riscatto di token e proprietà utente.

La sezione seguente fornisce altri dettagli sulla gestione degli errori per l'app.

Gestione degli errori in MSAL.js

MSAL.js fornisce oggetti errore che riepilogano e classificano i diversi tipi di errori comuni. Fornisce inoltre un'interfaccia per accedere a dettagli specifici degli errori, ad esempio i messaggi di errore, per gestirli in modo appropriato.

Oggetto errore

export class AuthError extends Error {
    // This is a short code describing the error
    errorCode: string;
    // This is a descriptive string of the error,
    // and may also contain the mitigation strategy
    errorMessage: string;
    // Name of the error class
    this.name = "AuthError";
}

Estendendo la classe Error, è possibile accedere alle proprietà seguenti:

• AuthError.message: uguale a errorMessage.
• AuthError.stack: analisi dello stack per gli errori generati.

Tipi di errore

Sono disponibili i tipi di errore seguenti:

• AuthError: classe Error di base per la libreria MSAL.js, usata anche per gli errori imprevisti.

• ClientAuthError: classe di errore che indica un problema con l'autenticazione client. La maggior parte degli errori che provengono dalla libreria sono ClientAuthErrors. Questi errori possono essere causati da chiamate a un metodo di accesso quando l'accesso è già in corso, utenti che annullano l'accesso e così via.

• ClientConfigurationError: classe di errore che estende ClientAuthError. Viene generato prima che le richieste vengano effettuate quando i parametri di configurazione dell'utente specificato non sono validi o sono mancanti.

• ServerError: classe di errore che rappresenta le stringhe di errore inviate dal server di autenticazione. Questi errori possono essere parametri o formati della richiesta non validi oppure eventuali altri errori che impediscono al server di eseguire l'autenticazione o l'autorizzazione dell'utente.

• InteractionRequiredAuthError classe di errore che estende ServerError per rappresentare gli errori del server che richiedono una chiamata interattiva. Questo errore viene generato da acquireTokenSilent se è necessario che l'utente interagisca con il server per fornire le credenziali o il consenso per l'autenticazione/autorizzazione. I codici errore includono "interaction_required", "login_required" e "consent_required".

Per la gestione degli errori nei flussi di autenticazione con metodi di reindirizzamento (loginRedirect, acquireTokenRedirect), sarà necessario gestire la promessa di reindirizzamento che è chiamata con esito positivo o negativo dopo il reindirizzamento tramite il metodo handleRedirectPromise() come indicato di seguito:

const msal = require('@azure/msal-browser');
const myMSALObj = new msal.PublicClientApplication(msalConfig);

// Register Callbacks for redirect flow
myMSALObj.handleRedirectPromise()
    .then(function (response) {
        //success response
    })
    .catch((error) => {
        console.log(error);
    })
myMSALObj.acquireTokenRedirect(request);

I metodi per l'esperienza popup (loginPopup, acquireTokenPopup) restituiscono promesse, pertanto è possibile usare il modello per le promesse (.then e .catch) per gestirli, come illustrato di seguito:

myMSALObj.acquireTokenPopup(request).then(
    function (response) {
        // success response
    }).catch(function (error) {
        console.log(error);
    });

Errori che richiedono l'interazione

Quando si tenta di usare un metodo non interattivo per acquisire un token, ad esempio acquireTokenSilent, viene restituito un errore, ma per MSAL non è stato possibile eseguire l'operazione in modo invisibile all'utente.

Le possibili cause sono:

• è necessario eseguire l'accesso
• è necessario fornire il consenso
• è necessario usare un'esperienza con autenticazione a più fattori.

La correzione consiste nel chiamare un metodo interattivo, ad esempio acquireTokenPopup o acquireTokenRedirect:

// Request for Access Token
myMSALObj.acquireTokenSilent(request).then(function (response) {
    // call API
}).catch( function (error) {
    // call acquireTokenPopup in case of acquireTokenSilent failure
    // due to interaction required
    if (error instanceof InteractionRequiredAuthError) {
        myMSALObj.acquireTokenPopup(request).then(
            function (response) {
                // call API
            }).catch(function (error) {
                console.log(error);
            });
    }
});

Accesso Condizionale e richieste di attestazioni

Se i token vengono recuperati in modalità invisibile all'utente, l'applicazione potrebbe riscontrare errori quando una richiesta di verifica delle attestazioni di accesso condizionale, ad esempio criteri di autenticazione a più fattori, è necessaria per un'API a cui si sta tentando di accedere.

Il modello per gestire questo errore consiste nell'acquisire in modo interattivo un token tramite MSAL. Ciò attiva una richiesta all'utente e offre a quest'ultimo la possibilità di soddisfare i criteri di accesso condizionale richiesti.

Quando si chiama un'API che richiede l'Accesso Condizionale, in alcuni casi è possibile ricevere una richiesta di attestazioni nell'errore dall'API. Ad esempio se i criteri di accesso condizionale devono avere un dispositivo gestito (Intune), l'errore sarà simile a AADSTS53000: il dispositivo deve essere gestito per accedere a questa risorsa o qualcosa di simile. In questo caso, è possibile passare le attestazioni nella chiamata per l'acquisizione del token, in modo che all'utente venga richiesto di soddisfare i criteri appropriati.

Quando i token vengono recuperati in modalità invisibile all'utente (tramite acquireTokenSilent) usando MSAL.js, l'applicazione potrebbe riscontrare errori quando l'API a cui si tenta di accedere richiede una verifica delle attestazioni di accesso condizionale, ad esempio criteri di autenticazione a più fattori.

Il modello per gestire questo errore consiste nell'effettuare una chiamata interattiva per acquisire il token in MSAL.js, ad esempio acquireTokenPopup o acquireTokenRedirect, come nell'esempio seguente:

myMSALObj.acquireTokenSilent(accessTokenRequest).then(function(accessTokenResponse) {
    // call API
}).catch(function(error) {
    if (error instanceof InteractionRequiredAuthError) {
    
        // extract, if exists, claims from the error object
        if (error.claims) {
            accessTokenRequest.claims = error.claims,
        
        // call acquireTokenPopup in case of InteractionRequiredAuthError failure
        myMSALObj.acquireTokenPopup(accessTokenRequest).then(function(accessTokenResponse) {
            // call API
        }).catch(function(error) {
            console.log(error);
        });
    }
});

L'acquisizione del token in modalità interattiva visualizza una richiesta all'utente e offre a quest'ultimo la possibilità di soddisfare i criteri di Accesso Condizionale richiesti.

Quando si chiama un'API che richiede l'Accesso Condizionale, è possibile ricevere una richiesta di attestazioni nell'errore dall'API. In questo caso, è possibile passare le attestazioni restituite nell'errore al parametro claims nell'oggetto richiesta token di accesso per soddisfare i criteri appropriati.

Vedere Come usare le API abilitate per la valutazione continua dell'accesso nelle applicazioni per altri dettagli.

Uso di altri framework

L'uso di toolkit come Tauri per le applicazioni a pagina singola registrate con la piattaforma di identità non è riconosciuto per le app di produzione. Le applicazioni a pagina singola supportano solo gli URL che iniziano con https per le app di produzione e http://localhost per lo sviluppo locale. I prefissi come tauri://localhost non possono essere usati per le app del browser. Questo formato può essere supportato solo per le app Web o per dispositivi mobili perché hanno un componente riservato a differenza delle app browser.

Nuovi tentativi dopo errori ed eccezioni

Si prevede di implementare i criteri di ripetizione dei retry quando si chiama MSAL. MSAL effettua chiamate HTTP al servizio Microsoft Entra e occasionalmente possono verificarsi errori. Ad esempio la rete può essere soggetta a malfunzionamenti o il server è sovraccarico.

HTTP 429

Quando il servizio token di sicurezza è sovraccarico a causa di un numero eccessivo di richieste, restituisce l'errore HTTP 429 con un suggerimento sul tempo disponibile per riprovare nel campo della risposta Retry-After.

Passaggi successivi

Considerare la possibilità di abilitare l'accesso MSAL.js per diagnosticare ed eseguire il debug dei problemi