Hibák és kivételek kezelése az MSAL.js-ben

Ez a cikk áttekintést nyújt a gyakori bejelentkezési hibák kezelésére vonatkozó különböző típusú hibákról és javaslatokról.

Az MSAL hibakezelési alapjai

A Microsoft Authentication Library (MSAL) kivételei az alkalmazásfejlesztőknek szólnak a hibaelhárításhoz, nem pedig a végfelhasználóknak való megjelenítéshez. A kivételüzenetek nincsenek honosítva.

A kivételek és hibák feldolgozásakor a kivételtípust és a hibakódot használhatja a kivételek megkülönböztetéséhez. A hibakódok listáját a Microsoft Entra hitelesítési és engedélyezési hibakódjaiban találja.

A bejelentkezés során hibák léphetnek fel a hozzájárulásokkal, a feltételes hozzáféréssel (MFA, Eszközkezelés, helyalapú korlátozások), a jogkivonatok kiállításával és beváltásakor, valamint a felhasználói tulajdonságokkal kapcsolatban.

Az alábbi szakasz további részleteket tartalmaz az alkalmazás hibakezeléséről.

Hibakezelés a MSAL.js

MSAL.js olyan hibaobjektumokat biztosít, amelyek elvonják és osztályozzák a gyakori hibák különböző típusait. Emellett egy felületet is biztosít a hibák bizonyos részleteinek, például a hibaüzenetek megfelelő kezeléséhez.

Hibaobjektum

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

A hibaosztály kibővítésével a következő tulajdonságokhoz férhet hozzá:

• AuthError.message: Ugyanaz, mint a errorMessage.
• AuthError.stack: Stack trace for thrown errors.

Hibatípusok

A következő hibatípusok érhetők el:

• AuthError: A MSAL.js könyvtár alapszintű hibaosztálya, amely szintén váratlan hibákhoz használatos.

• ClientAuthError: Az ügyfél-hitelesítéssel kapcsolatos problémát jelző hibaosztály. A kódtárból származó legtöbb hiba a ClientAuthErrors. Ezek a hibák olyan dolgokból erednek, mint a bejelentkezési módszer meghívása, amikor a bejelentkezés már folyamatban van, a felhasználó megszakítja a bejelentkezést stb.

• ClientConfigurationError: A kiterjesztő ClientAuthErrorhibaosztály. A rendszer a kérések előtt küldi el, amikor a megadott felhasználói konfigurációs paraméterek helytelenek vagy hiányoznak.

• ServerError: Hibaosztály, amely a hitelesítési kiszolgáló által küldött hibasztringeket jelöli. Ezek a hibák lehetnek érvénytelen kérelemformátumok vagy paraméterek, vagy bármely más hiba, amely megakadályozza a kiszolgálót a felhasználó hitelesítésében vagy engedélyezésében.

• InteractionRequiredAuthError: Hibaosztály, amely a kiszolgálóhibákra terjed ki ServerError , amelyek interaktív hívást igényelnek. Ezt a hibát az okozza acquireTokenSilent , ha a felhasználónak a kiszolgálóval kell kommunikálnia a hitelesítő adatok megadásához vagy a hitelesítéshez/engedélyezéshez való hozzájáruláshoz. A hibakódok közé tartozik az "interaction_required", "login_required"és "consent_required"a .

Az átirányítási módszerekkel (loginRedirect, acquireTokenRedirect) rendelkező hitelesítési folyamatokban a hibakezeléshez kezelnie kell az átirányítási ígéretet, amelyet az átirányítás után sikeres vagy sikertelen hívásnak nevezünk a metódus használatával az handleRedirectPromise() alábbiak szerint:

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

Az előugró felület (loginPopup, acquireTokenPopup) metódusai ígéreteket adnak vissza, így az ígéretminta (.then és .catch) használatával kezelheti őket az alábbi módon:

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

Beavatkozást igénylő hibák

A rendszer hibát ad vissza, ha nem interaktív metódust próbál meg használni egy olyan jogkivonat beszerzéséhez, mint például acquireTokenSilent, de az MSAL nem tudta csendben végrehajtani.

A lehetséges okok a következők:

• be kell jelentkeznie
• hozzájárulásra van szüksége
• többtényezős hitelesítést kell elvégeznie.

A szervizelés egy interaktív metódus meghívása, például acquireTokenPopupacquireTokenRedirect:

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

Feltételes hozzáféréssel és jogcímekkel kapcsolatos kihívások

A jogkivonatok csendes lekérésekor előfordulhat, hogy az alkalmazás hibaüzenetet kap, ha egy elérni kívánt API feltételes hozzáférési jogcímekkel kapcsolatos kihívásra , például MFA-szabályzatra van szükség.

A hiba kezelésének mintája egy jogkivonat interaktív beszerzése az MSAL használatával. Ez kéri a felhasználót, és lehetőséget ad nekik a szükséges feltételes hozzáférési szabályzat teljesítésére.

Bizonyos esetekben, amikor feltételes hozzáférést igénylő API-t hív meg, jogcímekkel kapcsolatos kihívást kaphat az API-tól kapott hibában. Ha például a feltételes hozzáférési szabályzat egy felügyelt eszközre (Intune) van szükség, a hiba a következőhöz hasonló lesz, mint AADSTS53000: Az eszköznek felügyeltnek kell lennie az erőforrás eléréséhez vagy valami hasonlóhoz. Ebben az esetben átadhatja a jogcímeket a jogkivonat-beolvasási hívásban, hogy a rendszer a megfelelő szabályzat teljesítésére kérje a felhasználót.

Ha a jogkivonatokat csendesen (használvaacquireTokenSilent) kéri le a MSAL.js, az alkalmazás hibaüzeneteket kaphat, amikor a elérni kívánt API feltételes hozzáférési jogcímekkel kapcsolatos kihívást, például MFA-szabályzatot igényel.

A hiba kezelésére szolgáló minta egy interaktív hívás, amely jogkivonatot kér le MSAL.js, például acquireTokenPopupacquireTokenRedirect az alábbi példában:

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

A jogkivonat interaktív beszerzése kéri a felhasználót, és lehetőséget ad nekik a szükséges feltételes hozzáférési szabályzat teljesítésére.

Ha feltételes hozzáférést igénylő API-t hív meg, jogcímekkel kapcsolatos kihívást kaphat az API-tól kapott hibában. Ebben az esetben a hiba által visszaadott jogcímeket átadhatja a claims hozzáférési jogkivonat-kérelem objektum paraméterének, hogy megfeleljen a megfelelő szabályzatnak.

További részletekért lásd : Folyamatos hozzáférés-kiértékeléssel kompatibilis API-k használata az alkalmazásokban .

Más keretrendszerek használata

Az éles alkalmazások nem ismerik fel az olyan eszközkészleteket, mint a Tauri a regisztrált egyoldalas alkalmazásokhoz (SPA-khoz) az identitásplatformmal. Az SPA-k csak az éles alkalmazásokhoz és http://localhost a helyi fejlesztéshez kezdődő https URL-címeket támogatják. A böngészőalkalmazásokhoz hasonló tauri://localhost előtagok nem használhatók. Ez a formátum csak mobil- vagy webalkalmazások esetében támogatott, mivel a böngészőalkalmazásokkal ellentétben bizalmas összetevővel rendelkeznek.

Újrapróbálkozás hibák és kivételek után

Az MSAL hívása során saját újrapróbálkozési szabályzatokat kell implementálnia. Az MSAL HTTP-hívásokat indít a Microsoft Entra szolgáltatáshoz, és időnként hibák léphetnek fel. A hálózat például leállhat, vagy a kiszolgáló túlterhelt.

HTTP 429

Ha a szolgáltatásjogkivonat-kiszolgáló (STS) túl sok kéréssel van túlterhelve, a 429-ben megadott HTTP-hibát adja vissza, és jelzi, hogy mennyi ideig lehet újra próbálkozni a Retry-After válaszmezőben.

Következő lépések

Fontolja meg a MSAL.js naplózásának engedélyezését a problémák diagnosztizálásához és hibakereséséhez