Logowanie w MSAL.NET

MSAL.NET aplikacje generują komunikaty dziennika, które mogą pomóc w diagnozowaniu problemów. Rejestrowanie można skonfigurować przy użyciu kilku wierszy kodu i mieć niestandardową kontrolę nad poziomem szczegółowości i tego, czy są rejestrowane dane osobiste i organizacyjne. Rejestrowanie nie jest domyślnie włączone. Zalecamy włączenie rejestrowania MSAL, aby użytkownicy mogli przesyłać dzienniki, gdy wystąpią problemy z uwierzytelnianiem. Należy pamiętać, że biblioteka MSAL nie przechowuje żadnych dzienników, lecz przekazuje komunikaty dziennika do lokalizacji określonej w implementacji rejestratora.

Note

Począwszy od MSAL.NET 4.58.0 deweloperzy mogą również używać biblioteki OpenTelemetry do agregowania dzienników i mierzenia wydajności aplikacji.

Poziomy rejestrowania

Istnieje kilka poziomów szczegółowości rejestrowania:

LogAlways: poziom podstawowy zawierający dzienniki ważnych metryk kondycji, które ułatwiają diagnostykę operacji biblioteki MSAL.
Critical: Dzienniki, które opisują nieodwracalną awarię aplikacji lub systemu albo katastrofalną awarię, która wymaga natychmiastowej uwagi.
Error: wskazuje, że wystąpił problem i został wygenerowany błąd. Służy do debugowania i identyfikowania problemów.
Warning: zawiera dzienniki w scenariuszach, w których niekoniecznie wystąpił błąd lub awaria, ale są przeznaczone do diagnostyki i ustalania problemów. Jest to zalecany minimalny poziom, który powinien być włączony w aplikacjach produkcyjnych.
Informational: biblioteka MSAL będzie rejestrować zdarzenia przeznaczone do celów informacyjnych, niekoniecznie przeznaczone do debugowania.
Verbose: MSAL zapisuje w dzienniku pełne szczegóły działania biblioteki. W środowisku produkcyjnym poziom szczegółowości logowania należy włączać tylko tymczasowo, aby zebrać dzienniki na potrzeby konkretnego debugowania.

Dane osobowe i organizacyjne

Domyślnie rejestrator MSAL nie rejestruje żadnych szczególnie chronionych danych osobowych ani danych organizacyjnych. Biblioteka udostępnia opcję włączania rejestrowania danych osobistych i organizacyjnych, jeśli zdecydujesz się to zrobić. Aby uzyskać szczegółowe informacje, zobacz Obsługa danych osobowych w MSAL.NET.

Konfigurowanie logowania w MSAL.NET

W bibliotece MSAL rejestrowanie jest ustawiane podczas tworzenia aplikacji przy użyciu konstruktora WithLogging(IIdentityLogger, Boolean) . Ta metoda przyjmuje następujące parametry:

identityLoggerto implementacja rejestrowania używana przez MSAL.NET do tworzenia dzienników na potrzeby debugowania lub sprawdzania kondycji. Dzienniki są wysyłane tylko w przypadku włączenia rejestrowania.
enablePiiLogging włącza rejestrowanie danych osobistych i organizacyjnych (PII), jeśli ustawiono wartość true. Domyślnie ten parametr ma wartość false, aby aplikacja nie rejestrowała poufnych danych.

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

Note

Biblioteki wyższego poziomu (Microsoft.Identity.Web, Microsoft.IdentityModel) udostępniają już implementacje tego interfejsu dla różnych środowisk (w szczególności ASP.NET Core).

Implementacja IIdentityLogger

Poziom rejestrowania z pliku konfiguracyjnego

Zdecydowanie zaleca się skonfigurowanie kodu w celu użycia pliku konfiguracji w środowisku w celu ustawienia poziomu dziennika, ponieważ umożliwi kodowi zmianę poziomu rejestrowania biblioteki MSAL bez konieczności ponownego kompilowania lub ponownego uruchamiania aplikacji. Ma to kluczowe znaczenie dla celów diagnostycznych, dzięki czemu można szybko zebrać wymagane dzienniki z aplikacji, która jest obecnie wdrożona w środowisku produkcyjnym. Szczegółowe rejestrowanie może być kosztowne, dlatego najlepiej domyślnie używać poziomu Informational i włączać szczegółowe rejestrowanie w przypadku wystąpienia problemu. Zobacz przykład dostawcy konfiguracji JSON , aby dowiedzieć się, jak ładować dane z pliku konfiguracji bez ponownego uruchamiania aplikacji.

Poziom dziennika ze zmiennej środowiskowej

Inną zalecaną opcją jest skonfigurowanie kodu pod kątem używania zmiennej środowiskowej na maszynie w celu ustawienia poziomu dziennika, ponieważ umożliwi kodowi zmianę poziomu rejestrowania biblioteki MSAL bez konieczności ponownego kompilowania aplikacji.

Zobacz EventLogLevel, aby uzyskać szczegółowe informacje na temat dostępnych poziomów logowania.

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

Używając MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Rejestrowanie w rozproszonej pamięci podręcznej tokenów

Jeśli używasz serializatorów pamięci podręcznej tokenów z pakietu Microsoft.Identity.Web.TokenCache w środowisku .NET, możesz włączyć dodatkowe dzienniki dotyczące buforowania.

Aby włączyć rejestrowanie rozproszonej pamięci podręcznej, ustaw właściwość MinLevel na Debug.

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

Zobacz Implementowanie niestandardowego dostawcy rejestrowania, aby uzyskać więcej informacji.

Identyfikator korelacji

Dzienniki pomagają zrozumieć zachowanie biblioteki MSAL po stronie klienta. Aby zrozumieć, co dzieje się po stronie usługi, zespół potrzebuje identyfikatora korelacji. Ten identyfikator śledzi żądanie uwierzytelniania za pośrednictwem różnych usług zaplecza.

Identyfikator korelacji można uzyskać na trzy sposoby:

Na podstawie pomyślnego wyniku uwierzytelnienia: AuthenticationResult.CorrelationId.
Z wyjątku usługi: MsalException.CorrelationId.
Przekazując niestandardowy identyfikator korelacji do WithCorrelationId(Guid) podczas tworzenia żądania tokena.

Podczas podawania własnego identyfikatora korelacji użyj innej wartości identyfikatora dla każdego żądania. Nie używaj stałej wartości, ponieważ nie będziemy w stanie odróżnić poszczególnych żądań.

Ślady sieci

Ważna

Dane śledzenia sieci zwykle zawierają dane osobowe i poświadczenia. Usuń wszelkie poufne szczegóły przed opublikowaniem dzienników na GitHub.

W przypadkach, w których szczegółowe dzienniki nie dostarczają wystarczających informacji, możesz przechwycić ślad sieciowy za pomocą narzędzi takich jak Fiddler lub mitmproxy. Możesz skonfigurować wybrane narzędzie jako lokalny serwer proxy i akceptować ruch z urządzeń w sieci lokalnej, umożliwiając przechwytywanie śladów z innych urządzeń, takich jak telefony iPhone lub Android. Konfiguracja specyficzna dla platformy może być wymagana przed przechwytywaniem dzienników.

Jeśli nie można użyć takiego narzędzia, można zmodyfikować HttpClient, którego biblioteka MSAL używa do rejestrowania ruchu HTTP. Aby uzyskać informacje, zobacz tę niestandardową HttpClient implementację z rejestrowaniem.

Warning

Ten klient nie powinien być używany w środowisku produkcyjnym i tylko do rejestrowania.

Niestandardowe HttpClient można dodać w następujący sposób:

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

Ślady sieci podczas korzystania z WAM

Aby zbierać ślady sieci dla menedżera kont sieci Web (WAM) w Windows za pomocą programu Fiddler, potrzebne są kilka dodatkowych kroków.

Włącz loopback dla AppContainer w Fiddlerze, klikając pozycję WinConfig, wybierając pozycję Exempt All i zapisując zmiany.

Interfejs wykluczania w programie Fiddler przedstawiający wszystkie aplikacje w oknie dialogowym WinConfig.

Włącz odszyfrowywanie HTTPS, ale wyklucz usługę ADFS (msft.sts.microsoft.com) z odszyfrowywania HTTPS:

Zrzut ekranu przedstawiający opcje programu Fiddler pokazujący sposób konfigurowania odszyfrowywania HTTPS

Last updated on 2026-07-02