MSAL.NET 로그인

MSAL.NET 앱은 문제를 진단하는 데 도움이 되는 로그 메시지를 생성합니다. 몇 줄의 코드로 로깅을 구성하고 세부 수준 및 개인 및 조직 데이터 로깅 여부를 사용자 지정 제어할 수 있습니다. 로깅은 기본적으로 사용하도록 설정되지 않습니다. 사용자가 인증 문제가 있을 때 로그를 제출할 수 있는 방법을 제공하기 위해 MSAL 로깅을 사용하도록 설정하는 것이 좋습니다. MSAL은 로그를 저장하지 않고 로거 구현에 제공된 대상으로 로그를 내보낸다.

메모

MSAL.NET 4.58.0부터 개발자는 OpenTelemetry를 사용하여 로그를 집계하고 애플리케이션 성능을 측정할 수도 있습니다.

로깅 수준

다음과 같은 여러 수준의 로깅 세부 정보가 있습니다.

LogAlways: MSAL 작업의 진단에 도움이 되는 중요한 상태 메트릭 로그를 포함하는 기본 수준입니다.
Critical: 복구할 수 없는 애플리케이션 또는 시스템 충돌 또는 즉각적인 주의가 필요한 치명적인 오류를 설명하는 로그입니다.
Error: 문제가 발생하여 오류가 발생했음을 나타냅니다. 문제를 디버깅하고 식별하는 데 사용됩니다.
Warning: 오류 또는 오류가 반드시 발생한 것은 아니지만 진단 및 문제를 정확히 파악하기 위한 시나리오의 로그를 포함합니다. 프로덕션 앱에서 사용하도록 설정해야 하는 권장 최소 수준입니다.
Informational: MSAL은 반드시 디버깅을 위한 것이 아니라 정보 제공을 위한 이벤트를 기록합니다.
Verbose: MSAL은 라이브러리 동작의 전체 세부 정보를 기록합니다. 프로덕션 환경에서는 특정 디버깅 목적으로 로그를 수집하기 위해 자세한 정보 표시 수준을 일시적으로만 사용하도록 설정해야 합니다.

개인 및 조직 데이터

기본적으로 MSAL 로거는 매우 중요한 개인 또는 조직 데이터를 캡처하지 않습니다. 라이브러리는 사용자가 원할 경우 개인 및 조직 데이터의 로깅을 활성화할 수 있는 옵션을 제공합니다. 자세한 내용은 MSAL.NET 개인 식별 정보 처리를 참조하세요.

MSAL.NET 로깅 구성

MSAL에서 로깅은 작성기를 WithLogging(IIdentityLogger, Boolean) 사용하여 애플리케이션을 만드는 동안 설정됩니다. 이 메서드는 다음 매개 변수를 사용합니다.

identityLogger는 MSAL.NET 디버깅 또는 상태 검사 목적으로 로그를 생성하는 데 사용하는 로깅 구현입니다. 로그는 로깅을 사용하는 경우에만 전송됩니다.
enablePiiLogging 에서는 true로 설정된 경우 개인 및 조직 데이터(PII)를 로깅할 수 있습니다. 기본적으로 이 매개 변수는 false로 설정되므로 애플리케이션에서 중요한 데이터를 기록하지 않습니다.

IIdentityLogger 인터페이스

namespace Microsoft.IdentityModel.Abstractions
{
    public interface IIdentityLogger
    {
        //
        // Summary:
        //     Checks to see if logging is enabled at given eventLogLevel.
        //
        // Parameters:
        //   eventLogLevel:
        //     Log level of a message.
        bool IsEnabled(EventLogLevel eventLogLevel);

        //
        // Summary:
        //     Writes a log entry.
        //
        // Parameters:
        //   entry:
        //     Defines a structured message to be logged at the provided Microsoft.IdentityModel.Abstractions.LogEntry.EventLogLevel.
        void Log(LogEntry entry);
    }
}

메모

상위 수준 라이브러리(Microsoft.Identity.Web, Microsoft.IdentityModel)는 이미 다양한 환경(특히 ASP.NET Core)에 대해 이 인터페이스의 구현을 제공합니다.

IIdentityLogger 구현

구성 파일의 로그 수준

애플리케이션을 다시 빌드하거나 다시 시작하지 않고도 코드가 MSAL 로깅 수준을 변경할 수 있도록 하므로 사용자 환경에서 구성 파일을 사용하여 로그 수준을 설정하도록 코드를 구성하는 것이 좋습니다. 이는 진단 목적으로 중요하므로 현재 프로덕션에 배포된 애플리케이션에서 필요한 로그를 신속하게 수집할 수 있습니다. 상세 로깅은 비용이 많이 들 수 있으므로 기본적으로는 Informational 수준을 사용하고, 문제가 발생하면 상세 로깅을 사용하도록 설정하는 것이 가장 좋습니다. 애플리케이션을 다시 시작하지 않고 구성 파일에서 데이터를 로드하는 방법에 대한 예제는 JSON 구성 공급자 를 참조하세요.

환경 변수의 로그 수준

권장하는 또 다른 옵션은 애플리케이션을 다시 빌드하지 않고도 코드가 MSAL 로깅 수준을 변경할 수 있도록 컴퓨터에서 환경 변수를 사용하여 로그 수준을 설정하도록 코드를 구성하는 것입니다.

사용 가능한 로그 수준에 대한 자세한 내용은 참조 EventLogLevel 하세요.

Example:

class MyIdentityLogger : IIdentityLogger
{
    public EventLogLevel MinLogLevel { get; }

    public MyIdentityLogger()
    {
        //Retrieve the log level from an environment variable
        var msalEnvLogLevel = Environment.GetEnvironmentVariable("MSAL_LOG_LEVEL");

        if (Enum.TryParse(msalEnvLogLevel, out EventLogLevel msalLogLevel))
        {
            MinLogLevel = msalLogLevel;
        }
        else
        {
            //Recommended default log level
            MinLogLevel = EventLogLevel.Informational;
        }
    }

    public bool IsEnabled(EventLogLevel eventLogLevel)
    {
        return eventLogLevel <= MinLogLevel;
    }

    public void Log(LogEntry entry)
    {
        //Log Message here:
        Console.WriteLine(entry.Message);
    }
}

MyIdentityLogger을 사용:

MyIdentityLogger myLogger = new MyIdentityLogger();

var app = ConfidentialClientApplicationBuilder
    .Create(TestConstants.ClientId)
    .WithClientSecret("secret")
    .WithLogging(myLogger, enablePiiLogging)
    .Build();

분산 토큰 캐시에 로깅

.NET에서 Microsoft.Identity.Web.TokenCache 패키지의 토큰 캐시 serializer를 사용하는 경우 추가 캐시 로그를 활성화할 수 있습니다.

분산 캐시 로깅을 사용하도록 설정하려면 MinLevel 속성을 Debug로 설정합니다.

     app.AddDistributedTokenCache(services =>
     {
          services.AddDistributedMemoryCache();
          services.AddLogging(configure => configure.AddConsole())
               .Configure<LoggerFilterOptions>(options => options.MinLevel = Microsoft.Extensions.Logging.LogLevel.Debug);
     });

자세한 내용은 사용자 지정 로깅 공급자 구현 을 참조하세요.

상관 관계 ID

로그는 클라이언트 쪽의 MSAL 동작을 이해하는 데 도움이 됩니다. 서비스 쪽에서 발생하는 일을 이해하려면 팀에 상관 관계 ID가 필요합니다. 이 ID는 다양한 백 엔드 서비스를 통해 인증 요청을 추적합니다.

상관 관계 ID는 다음 세 가지 방법으로 얻을 수 있습니다.

성공적인 인증 결과에서: AuthenticationResult.CorrelationId.
서비스 예외에서: MsalException.CorrelationId.
토큰 요청을 빌드할 때 사용자 지정 상관 관계 ID를 WithCorrelationId(Guid) 전달합니다.

고유한 상관 관계 ID를 제공할 때 각 요청에 대해 다른 ID 값을 사용합니다. 요청을 구분할 수 없으므로 상수는 사용하지 마세요.

네트워크 추적

Important

네트워크 추적에는 일반적으로 개인 식별이 가능한 정보 및 자격 증명이 포함됩니다. GitHub 로그를 게시하기 전에 중요한 세부 정보를 제거합니다.

자세한 정보 표시 로그가 충분한 인사이트를 제공하지 않는 경우 Fiddler 또는 mitmproxy같은 도구를 사용하여 네트워크 추적을 가져올 수 있습니다. 선택한 도구를 로컬 프록시로 구성하고 로컬 네트워크의 디바이스에서 트래픽을 허용하여 iPhone 또는 Android 휴대폰과 같은 다른 장치에서 추적을 캡처할 수 있습니다. 로그를 캡처하기 전에 플랫폼별 구성이 필요할 수 있습니다.

이러한 도구를 사용할 수 없는 경우 MSAL에서 HTTP 트래픽을 HttpClient 기록하기 위해 사용하는 도구를 수정할 수 있습니다. 참고로 로깅이 포함된 이 사용자 지정 HttpClient 구현을 참조하세요.

Warning

이 클라이언트는 프로덕션 및 로깅에만 사용해서는 안 됩니다.

다음과 같이 사용자 지정 HttpClient 을 추가할 수 있습니다.

var msalPublicClient = PublicClientApplicationBuilder
       .Create(ClientId)
       .WithHttpClientFactory(new HttpSnifferClientFactory())
       .Build();

WAM을 사용하는 경우 네트워크 추적

Fiddler를 사용하여 Windows WAM(웹 계정 관리자)에 대한 네트워크 추적을 수집하려면 몇 가지 추가 단계가 필요합니다.

WinConfig를 클릭하고 모두 제외를 선택하고 변경 내용을 저장하여 Fiddler에서 AppContainer 루프백을 사용하도록 설정합니다.

WinConfig 대화 상자의 모든 애플리케이션을 보여 주는 Fiddler의 예외 인터페이스입니다.

HTTPS 암호 해독을 사용하도록 설정하지만 HTTPS 암호 해독에서 ADFS(msft.sts.microsoft.com)를 제외합니다.

HTTPS 암호 해독을 구성하는 방법을 보여 주는 Fiddler 옵션의 스크린샷

Last updated on 2026-07-02