Menangani kesalahan dan pengecualian di MSAL.js

Artikel
2023-12-19

Artikel ini memberikan gambaran umum tentang berbagai jenis kesalahan dan rekomendasi untuk menangani kesalahan masuk yang umum.

Dasar-dasar penanganan kesalahan MSAL

Pengecualian di Microsoft Authentication Library (MSAL) ditujukan bagi pengembang aplikasi untuk memecahkan masalah, bukan untuk ditampilkan kepada pengguna akhir. Pesan pengecualian tidak dilokalisasi.

Saat memproses pengecualian dan kesalahan, Anda dapat menggunakan jenis pengecualian itu sendiri dan kode kesalahan untuk membedakan antara pengecualian. Untuk daftar kode kesalahan, lihat Kode kesalahan autentikasi dan otorisasi Microsoft Entra.

Selama pengalaman masuk, Anda mungkin mengalami kesalahan tentang persetujuan, Akses Bersyarat (MFA, Manajemen Perangkat, pembatasan berbasis lokasi), penerbitan dan penukaran token, dan properti pengguna.

Bagian berikut ini menyediakan detail selengkapnya tentang penanganan kesalahan untuk aplikasi Anda.

Menangani kesalahan di MSAL.js

MSAL.js menyediakan objek kesalahan yang abstrak dan mengklasifikasikan berbagai jenis kesalahan umum. MSAL.js juga menyediakan antarmuka untuk mengakses detail spesifik kesalahan, misalnya pesan kesalahan, untuk menanganinya dengan tepat.

Objek kesalahan

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

Dengan memperluas kelas kesalahan, Anda memiliki akses ke properti berikut:

AuthError.message: Sama seperti errorMessage.
AuthError.stack: Jejak tumpukan untuk kesalahan yang dilempar.

Jenis kesalahan

Jenis kesalahan berikut ini tersedia:

AuthError: Kelas kesalahan dasar untuk pustaka MSAL.js, juga digunakan untuk kesalahan yang tak terduga.
ClientAuthError: Kelas kesalahan yang menunjukkan masalah dengan autentikasi Klien. Sebagian besar kesalahan yang berasal dari pustaka adalah ClientAuthErrors. Kesalahan tersebut merupakan hasil dari hal seperti memanggil metode masuk ketika proses masuk sedang berlangsung, lalu pengguna membatalkan proses masuk, dan sebagainya.
ClientConfigurationError: Kelas kesalahan yang memperluas ClientAuthError. Ini dilemparkan sebelum permintaan dibuat ketika parameter konfigurasi pengguna yang diberikan salah bentuk atau hilang.
ServerError: Kelas kesalahan, mewakili untai (karakter) kesalahan yang dikirim oleh server autentikasi. Kesalahan ini mungkin format permintaan atau parameter yang tidak valid, atau kesalahan lain yang mencegah server mengautentikasi atau mengotorisasi pengguna.
InteractionRequiredAuthError: Kelas kesalahan, memperluas ServerError untuk mewakili kesalahan server, yang memerlukan panggilan interaktif. Kesalahan ini dibuang oleh acquireTokenSilent jika pengguna diharuskan untuk berinteraksi dengan server guna memberikan info masuk atau persetujuan untuk autentikasi/otorisasi. Kode kesalahan termasuk "interaction_required", "login_required", dan "consent_required".

Untuk penanganan kesalahan dalam alur autentikasi dengan metode pengalihan (loginRedirect, acquireTokenRedirect), Anda harus menangani promise pengalihan, yang dipanggil dengan keberhasilan atau kegagalan setelah pengalihan dengan menggunakan metode handleRedirectPromise() sebagai berikut:

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

Metode untuk pengalaman pop-up (loginPopup, acquireTokenPopup) mengembalikan janji, sehingga Anda dapat menggunakan pola janji (.then dan .catch) untuk menanganinya seperti yang ditunjukkan:

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

Kesalahan yang memerlukan interaksi

Kesalahan dihasilkan ketika Anda mencoba menggunakan metode noninteraktif untuk memperoleh token seperti acquireTokenSilent, tetapi MSAL tidak bisa melakukannya secara senyap.

Kemungkinan alasan:

Anda perlu masuk
Anda perlu menyetujui
Anda harus melalui pengalaman autentikasi multifaktor.

Remediasinya adalah memanggil metode interaktif seperti acquireTokenPopup atau 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);
            });
    }
});

Tantangan Akses Bersyarat dan Klaim

Saat mendapatkan token secara senyap, aplikasi Anda dapat menerima kesalahan saat Tantangan klaim Akses Bersyarat seperti kebijakan MFA diperlukan oleh API yang Anda coba akses.

Pola untuk menangani kesalahan ini adalah memperoleh token secara interaktif menggunakan MSAL. Hal ini meminta pengguna dan memberi mereka kesempatan untuk memenuhi kebijakan Akses Bersyarat yang diperlukan.

Dalam kasus tertentu, saat memanggil API yang memerlukan Akses Bersyarat, Anda dapat menerima tantangan klaim dalam kesalahan dari API. Misalnya jika kebijakan Akses Bersyarat adalah memiliki perangkat terkelola (Intune), kesalahan akan menjadi sesuatu seperti AADSTS53000: Perangkat Anda harus dikelola untuk mengakses sumber daya ini atau sesuatu yang serupa. Dalam hal ini, Anda dapat meneruskan klaim dalam panggilan perolehan token sehingga pengguna diminta untuk memenuhi kebijakan yang sesuai.

Saat mendapatkan token secara diam-diam (menggunakan acquireTokenSilent) menggunakan MSAL.js, aplikasi Anda mungkin menerima kesalahan saat API yang coba Anda akses memerlukan tantangan klaim Akses Bersyarat seperti kebijakan MFA.

Pola untuk menangani kesalahan ini adalah melakukan panggilan interaktif untuk memperoleh token dalam MSAL.js seperti acquireTokenPopup atau acquireTokenRedirect seperti dalam contoh berikut:

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

Dengan secara interaktif memperoleh token, pengguna diminta dan diberi kesempatan untuk mematuhi kebijakan Akses Bersyarat yang ditentukan.

Saat memanggil API yang memerlukan Akses Bersyarat, Anda dapat menerima tantangan klaim sebagai bagian dari kesalahan dari API. Dalam hal ini, Anda dapat meneruskan klaim yang dikembalikan dalam kesalahan ke claims parameter dalam objek permintaan token akses untuk memenuhi kebijakan yang sesuai.

Lihat Cara menggunakan API berkemampuan Evaluasi Akses Berkelanjutan di aplikasi Anda untuk detail selengkapnya.

Menggunakan kerangka kerja lain

Menggunakan toolkit seperti Tauri untuk aplikasi halaman tunggal (SPA) yang terdaftar dengan platform identitas tidak disarankan untuk aplikasi produksi. SPAs hanya mendukung URL yang dimulai dengan https untuk aplikasi produksi dan http://localhost untuk pengembangan lokal. Awalan seperti tauri://localhost tidak dapat digunakan untuk aplikasi browser. Format ini hanya dapat didukung untuk aplikasi seluler atau web karena memiliki komponen rahasia tidak seperti aplikasi browser.

Mencoba kembali setelah kesalahan dan pengecualian

Anda diharapkan untuk menerapkan kebijakan percobaan kembali milik Anda sendiri saat memanggil MSAL. MSAL melakukan panggilan HTTP ke layanan Microsoft Entra, dan terkadang kegagalan dapat terjadi. Misalnya jaringan dapat tidak berfungsi atau server kelebihan beban.

HTTP 429

Saat Server Token Layanan (STS) kelebihan beban dengan terlalu banyak permintaan, Server Token Layanan menampilkan kesalahan HTTP 429 dengan petunjuk tentang berapa lama hingga Anda dapat mencoba lagi di bidang respons Retry-After.

Langkah berikutnya

Pertimbangkan untuk mengaktifkan Pengelogan di MSAL.js untuk membantu Anda mendiagnosis dan men-debug masalah

Bagikan melalui