Zpracování chyb a výjimek v MSAL.js

  • Článek

Tento článek obsahuje přehled různých typů chyb a doporučení pro zpracování běžných chyb přihlašování.

Základy zpracování chyb MSAL

Výjimky v knihovně Microsoft Authentication Library (MSAL) jsou určené pro vývojáře aplikací, aby mohli řešit potíže, ne pro zobrazování koncovým uživatelům. Zprávy o výjimce nejsou lokalizované.

Při zpracování výjimek a chyb můžete k rozlišení mezi výjimkami použít samotný typ výjimky a kód chyby. Seznam kódů chyb naleznete v tématu Ověřování a autorizační kódy Microsoft Entra.

Během přihlašování se můžou zobrazit chyby týkající se souhlasů, podmíněného přístupu (MFA, Správa zařízení, omezení založených na poloze), vystavování a uplatnění tokenů a vlastností uživatele.

Následující část obsahuje další podrobnosti o zpracování chyb pro vaši aplikaci.

Zpracování chyb v MSAL.js

MSAL.js poskytuje chybové objekty, které abstrahují a klasifikují různé typy běžných chyb. Poskytuje také rozhraní pro přístup ke konkrétním podrobnostem o chybách, jako jsou chybové zprávy pro jejich správné zpracování.

Objekt chyby

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

Rozšířením třídy chyb máte přístup k následujícím vlastnostem:

  • AuthError.message: Stejné jako .errorMessage
  • AuthError.stack: Trasování zásobníku pro vyvolání chyb.

Typy chyb

K dispozici jsou následující typy chyb:

  • AuthError: Základní třída chyby pro knihovnu MSAL.js, která se používá také pro neočekávané chyby.

  • ClientAuthError: Třída chyby, která označuje problém s ověřováním klienta. Většina chyb, které pocházejí z knihovny, jsou ClientAuthErrors. Tyto chyby jsou výsledkem volání metody přihlášení, když už probíhá přihlášení, uživatel zruší přihlášení atd.

  • ClientConfigurationError: Třída chyby, která rozšiřuje ClientAuthError. Vyvolá se před provedením požadavků, když jsou dané parametry konfigurace uživatele poškozené nebo chybí.

  • ServerError: Error class, představuje chybové řetězce odeslané ověřovacím serverem. Tyto chyby můžou být neplatné formáty nebo parametry požadavků nebo jakékoli jiné chyby, které brání serveru v ověřování nebo autorizaci uživatele.

  • InteractionRequiredAuthError: Třída chyby, rozšiřuje ServerError o reprezentaci chyb serveru, které vyžadují interaktivní volání. Tato chyba se vyvolá v případě, že je uživatel nutný k interakci se serverem acquireTokenSilent za účelem poskytnutí přihlašovacích údajů nebo souhlasu s ověřováním nebo autorizací. Kódy chyb zahrnují "interaction_required", "login_required"a "consent_required".

Pro zpracování chyb v tocích ověřování pomocí metod přesměrování (loginRedirect, acquireTokenRedirect), budete muset zpracovat příslib přesměrování, který se volá s úspěchem nebo selháním po přesměrování pomocí handleRedirectPromise() metody následujícím způsobem:

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

Metody pro automaticky otevírané prostředí (loginPopup, acquireTokenPopup) vrací přísliby, takže můžete použít vzor příslibu (.then a .catch) k jejich zpracování, jak je znázorněno:

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

Chyby, které vyžadují interakci

Při pokusu o použití neinteraktivní metody získání tokenu, jako acquireTokenSilentje například , se vrátí chyba, ale msAL to neuděláte bezobslužně.

Možné důvody jsou:

  • musíte se přihlásit.
  • potřebujete souhlas
  • Potřebujete projít prostředím vícefaktorového ověřování.

Náprava spočívá v volání interaktivní metody, jako acquireTokenPopup je například: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);
            });
    }
});

Výzvy podmíněného přístupu a deklarací identity

Při tichém získávání tokenů může vaše aplikace obdržet chyby, když rozhraní API, ke které se pokoušíte získat přístup, vyžaduje výzva k deklaraci identity podmíněného přístupu, jako jsou zásady MFA.

Vzor pro zpracování této chyby spočívá v interaktivním získání tokenu pomocí knihovny MSAL. Tím uživatele vyzvete a získáte mu možnost splnit požadované zásady podmíněného přístupu.

V některýchpřípadechch Pokud například zásady podmíněného přístupu mají spravované zařízení (Intune), chyba bude vypadat přibližně jako AADSTS53000: Aby bylo možné k tomuto prostředku přistupovat, musí být vaše zařízení spravované nebo něco podobného. V takovém případě můžete předat deklarace identity ve volání tokenu získání, aby se uživateli zobrazila výzva k splnění příslušných zásad.

Při bezobslužné získávání tokenů (pomocí acquireTokenSilent) pomocí MSAL.js může aplikace obdržet chyby, když rozhraní API, ke které se pokoušíte získat přístup, vyžaduje výzvu deklarací podmíněného přístupu, jako jsou zásady vícefaktorového ověřování.

Model pro zpracování této chyby spočívá v interaktivním volání pro získání tokenu v MSAL.js jako acquireTokenPopup v acquireTokenRedirect následujícím příkladu:

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

Interaktivní získání tokenu vyzve uživatele a poskytne mu možnost splnit požadované zásady podmíněného přístupu.

Při volání rozhraní API vyžadujícího podmíněný přístup můžete z rozhraní API obdržet výzvu deklarace identity. V tomto případě můžete předat deklarace identity vrácené v chybě claims parametru v objektu žádosti o přístupový token, aby splňovaly příslušné zásady.

Další podrobnosti najdete v tématu Použití rozhraní API s podporou průběžného vyhodnocování přístupu v aplikacích .

Použití jiných architektur

Použití sad nástrojů, jako je Tauri pro registrované jednostránkové aplikace (SPA) s platformou identity, se pro produkční aplikace nerozpozná. SA podporují jenom adresy URL, které začínají https pro produkční aplikace a http://localhost místní vývoj. Předpony jako tauri://localhost se nedají použít pro aplikace v prohlížeči. Tento formát je možné podporovat jenom u mobilních nebo webových aplikací, protože mají důvěrnou komponentu na rozdíl od aplikací prohlížeče.

Opakování po chybách a výjimkách

Při volání knihovny MSAL byste měli implementovat vlastní zásady opakování. MsAL provádí volání HTTP do služby Microsoft Entra a občas může dojít k selháním. Například síť může jít dolů nebo je server přetížen.

HTTP 429

Pokud je server tokenů služby (STS) přetížen příliš mnoha požadavky, vrátí chybu HTTP 429 s nápovědou o tom, jak dlouho, než to můžete zkusit znovu v Retry-After poli odpovědi.

Další kroky

Zvažte povolení protokolování v MSAL.js , které vám pomůžou s diagnostikou a laděním problémů.