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

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 Identity a ověřování Microsoftu (MSAL) jsou určené pro vývojáře aplikací k řešení potíží, nikoli k zobrazení 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 najdete v tématu Kódy chyb ověřování a autorizace v Microsoft Entra.

Během přihlašování můžete narazit na 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 chyb 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é vrací knihovna, jsou chyby typu 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 výjimky, která rozšiřuje ClientAuthError a je vyvolána před odesláním požadavků, pokud jsou zadané parametry uživatelské konfigurace neplatné nebo chybějí.

  • 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, například acquireTokenSilent, se vrátí chyba, ale MSAL to nemohl provést bezobslužně.

Možné důvody jsou:

  • musíte se přihlásit.
  • potřebujete souhlas
  • Musíte projít vícefaktorovým ověřováním.

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

Podmíněný přístup a problémy s claimy

Při tichém získávání tokenů může ve vaší aplikaci docházet k chybám, pokud rozhraní API, ke kterému se pokoušíte získat přístup, vyžaduje výzvu deklarací podmíněného přístupu, například kvůli zásadám 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ých případech můžete při volání rozhraní API, které vyžaduje podmíněný přístup, obdržet v chybové odpovědi z rozhraní API výzvu deklarací. Pokud například zásada podmíněného přístupu vyžaduje spravované zařízení (Intune), chybová zpráva bude vypadat přibližně takto: AADSTS53000: Aby bylo možné získat přístup k tomuto prostředku, musí být vaše zařízení spravované nebo podobně. V takovém případě můžete ve volání pro získání tokenu předat claims, aby byl uživatel vyzván ke splnění příslušných zásad.

Při tichém získávání tokenů (pomocí acquireTokenSilent) pomocí MSAL.js může vaše aplikace obdržet chyby, pokud rozhraní API, ke kterému se pokoušíte získat přístup, vyžaduje výzvu deklarací v rámci podmíněného přístupu, například zásady MFA.

Model pro zpracování této chyby spočívá v interaktivním volání pro získání tokenu v MSAL.js, například acquireTokenPopupacquireTokenRedirect v 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, které vyžaduje podmíněný přístup, můžete v chybové odpovědi z rozhraní API obdržet výzvu k deklaracím identity. V tomto případě můžete deklarace vrácené v chybě předat do parametru claims v objektu žádosti o přístupový token, aby byly splněny požadavky příslušných zásad.

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 identit není pro produkční aplikace podporováno. Aplikace SPA podporují pouze adresy URL, které začínají na https pro produkční aplikace a na http://localhost pro lokální 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

Očekává se, že při volání knihovny MSAL implementujete vlastní zásady opakování pokusů. 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 se můžete zkusit znovu v poli odpovědi Retry-After.

Další kroky

Zvažte povolení protokolování v MSAL.js, které vám pomůže diagnostikovat a ladit problémy.

  • Last updated on