MSAL.js에서 오류 및 예외 처리

아티클
12/19/2023

이 문서에서는 다양한 유형의 오류를 개략적으로 설명하고 일반적인 로그인 오류 처리를 위한 권장 사항을 제공합니다.

MSAL 오류 처리 기본 사항

MSAL(Microsoft 인증 라이브러리)의 예외는 앱 개발자가 최종 사용자에게 표시하지 않고 문제를 해결하기 위한 것입니다. 예외 메시지는 지역화되지 않았습니다.

예외 및 오류를 처리할 때 예외 유형 자체와 오류 코드를 사용하여 예외를 구별할 수 있습니다. 오류 코드 목록은 Microsoft Entra 인증 및 권한 부여 오류 코드를 참조하세요.

로그인 환경에서 동의, 조건부 액세스(MFA, 디바이스 관리, 위치 기반 제한), 토큰 발급 및 상환 및 사용자 속성에 대한 오류가 발생할 수 있습니다.

다음 섹션에서는 앱의 오류 처리에 대한 자세한 정보를 제공합니다.

MSAL.js에서 오류 처리

MSAL.js는 여러 유형의 일반적인 오류를 추상화하고 분류 하는 오류 개체를 제공합니다. 또한 오류 메시지와 같은 오류에 대한 특정 세부 정보에 액세스하여 적절히 처리하기 위한 인터페이스도 제공합니다.

Error 개체

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

오류 클래스를 확장하면 다음 속성에 액세스할 수 있습니다.

AuthError.message: errorMessage와 같습니다.
AuthError.stack: throw된 오류에 대한 스택 추적입니다.

오류 형식

사용할 수 있는 오류 유형은 다음과 같습니다.

AuthError: MSAL.js 라이브러리의 기본 오류 클래스이며, 예기치 않은 오류에도 사용됩니다.
ClientAuthError: 클라이언트 인증 관련 문제를 나타내는 오류 클래스입니다. 라이브러리에서 발생하는 대부분의 오류는 ClientAuthErrors입니다. 이러한 오류는 로그인이 이미 진행 중이거나 사용자가 로그인을 취소하는 경우 등에 발생한 로그인 방법 호출과 같은 작업으로 인해 나타납니다.
ClientConfigurationError: ClientAuthError를 확장하는 오류 클래스입니다. 이는 지정한 사용자 구성 매개 변수가 누락되었거나 형식이 잘못된 경우 요청하기 전에 throw됩니다.
ServerError: 인증 서버에서 보낸 오류 문자열을 나타내는 오류 클래스입니다. 이러한 오류는 잘못된 요청 형식이나 매개 변수이거나 서버가 사용자를 인증하거나 권한을 부여하지 못하게 하는 기타 오류일 수 있습니다.
InteractionRequiredAuthError: 대화형 호출이 필요한 서버 오류를 나타내는 ServerError를 확장하는 오류 클래스입니다. 인증/권한 부여에 대한 자격 증명 또는 동의를 제공하기 위해 서버와 상호 작용해야 하는 경우 acquireTokenSilent에서 이 오류를 throw합니다. 오류 코드는 "interaction_required", "login_required" 및 "consent_required"를 포함합니다.

리디렉션 메서드(loginRedirect, acquireTokenRedirect)를 사용하여 인증 흐름에서 오류를 처리하려면 다음과 같이 handleRedirectPromise() 메서드를 사용하여 리디렉션 후 성공 또는 실패와 함께 호출되는 리디렉션 약속을 처리해야 합니다.

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

팝업 환경을 위한 메서드(loginPopup, acquireTokenPopup)는 약속을 반환하므로 약속 패턴(.then 및 .catch)을 사용하여 표시된 대로 처리할 수 있습니다.

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

상호 작용이 필요한 오류

acquireTokenSilent와 같은 토큰 획득 비대화형 메서드를 사용하려고 하지만 MSAL에서 자동으로 이 작업을 수행할 수 없는 경우 오류가 반환됩니다.

가능한 원인은 다음과 같습니다.

로그인해야 합니다.
동의해야 합니다.
다단계 인증 환경을 거쳐야 합니다.

업데이트 관리는 acquireTokenPopup 또는 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);
            });
    }
});

조건부 액세스 및 클레임 챌린지

토큰을 자동으로 가져올 때 액세스하려는 API에서 조건부 액세스 클레임 챌린지와 같은 MFA 정책이 필요한 경우 애플리케이션에서 오류가 발생할 수 있습니다.

이 오류를 처리하는 패턴은 MSAL을 사용하여 토큰을 대화형으로 획득하는 것입니다. 그러면 사용자에게 메시지가 표시되고 필요한 조건부 액세스 정책을 충족시킬 수 있는 기회가 제공됩니다.

조건부 액세스가 필요한 API를 호출하는 경우 클레임 챌린지를 API의 오류로 받을 수 있습니다. 예를 들어 조건부 액세스 정책에 관리 디바이스(Intune)가 있는 경우 오류는 AADSTS53000: 이 리소스에 액세스하려면 디바이스가 관리되어야 함이거나 이와 비슷합니다. 이 경우 토큰 획득 호출에서 클레임을 전달하여 사용자에게 적절한 정책을 충족시키라는 메시지가 표시되도록 할 수 있습니다.

MSAL.js를 사용하여 자동으로 토큰을 가져올 때(acquireTokenSilent 사용) 액세스하려는 API에서 MFA 정책과 같은 조건부 액세스 클레임 챌린지를 요구하면 애플리케이션에서 오류가 발생할 수 있습니다.

이 오류를 처리하는 패턴은 다음 예제와 같이 MSAL.js에서 토큰(예: acquireTokenPopup 또는 acquireTokenRedirect)을 획득하기 위해 대화형 호출을 수행하는 것입니다.

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

토큰을 대화형으로 획득하면 사용자에게 메시지가 표시되어 필요한 조건부 액세스 정책을 충족시킬 수 있는 기회가 제공됩니다.

조건부 액세스가 필요한 API를 호출할 때 클레임 챌린지를 API의 오류로 받을 수 있습니다. 이 경우 오류에서 반환된 클레임을 액세스 토큰 요청 개체의 claims 매개 변수에 전달하여 적절한 정책을 충족할 수 있습니다.

자세한 내용은 애플리케이션에서 지속적인 액세스 권한 평가 지원 API를 사용하는 방법을 참조하세요.

다른 프레임워크 사용

ID 플랫폼에 등록된 SPA(단일 페이지 애플리케이션)에 Tauri와 같은 도구 키트를 사용하는 것은 프로덕션 앱에서 인식되지 않습니다. SPA는 프로덕션 앱의 경우 https로 시작하고 로컬 개발의 경우 http://localhost로 시작하는 URL만 지원합니다. tauri://localhost와 같은 접두사는 브라우저 앱에 사용할 수 없습니다. 이 형식은 브라우저 앱과 달리 기밀 구성 요소가 있는 모바일 또는 웹앱에서만 지원됩니다.

오류 및 예외 후 다시 시도

MSAL을 호출할 때 사용자 고유의 재시도 정책을 구현해야 합니다. MSAL은 Microsoft Entra 서비스에 대한 HTTP 호출을 수행하고, 가끔 오류가 발생할 수 있습니다. 예를 들어 네트워크가 다운되거나 서버가 오버로드될 수 있습니다.

HTTP 429

STS(서비스 토큰 서버)가 너무 많은 요청으로 인해 오버로드되는 경우 Retry-After 응답 필드에서 다시 시도할 수 있을 때까지의 시간에 대한 힌트를 포함하는 HTTP 오류 429를 반환합니다.

다음 단계

문제를 진단하고 디버그할 수 있도록 MSAL.js에서 로깅을 사용하도록 설정하는 것이 좋습니다.

다음을 통해 공유