Вход в MSAL.NET

MSAL.NET приложения создают сообщения журнала, которые помогают диагностировать проблемы. Вы можете настроить ведение журнала с несколькими строками кода и настроить пользовательский контроль над уровнем детализации и регистрировать ли персональные и организационные данные. Ведение журнала по умолчанию не включено. Мы рекомендуем включить ведение журнала MSAL, чтобы пользователи могли отправлять журналы при наличии проблем с проверкой подлинности. Обратите внимание, что MSAL не хранит журналы и отправляет журналы в место назначения, предоставленное в реализации средства ведения журнала.

Note

Начиная с 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 включает ведение журнала персональных данных и данных организации (PII), если задано значение true. По умолчанию этот параметр имеет значение 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);
    }
}

Note

Библиотеки более высокого уровня (Microsoft.Identity.Web,Microsoft.IdentityModel) уже предоставляют реализации этого интерфейса для различных сред (в частности, ASP.NET Core).

Реализация IIdentityLogger

Уровень логирования из файла конфигурации

Настоятельно рекомендуется настроить код для использования файла конфигурации в вашей среде, чтобы задать уровень журнала, так как он позволит коду изменить уровень ведения журнала MSAL без необходимости перестроить или перезапустить приложение. Это важно для диагностических целей, что позволяет быстро собирать необходимые журналы из приложения, которое в настоящее время развернуто в рабочей среде. Подробное журналирование может быть ресурсоёмким, поэтому по умолчанию лучше использовать уровень Informational и включать подробное журналирование при возникновении проблемы. См. пример загрузки данных из файла конфигурации JSON без перезапуска приложения.

Уровень журналирования из переменной среды

Мы рекомендуем настроить код для использования переменной среды на компьютере, чтобы задать уровень журнала, так как он позволит коду изменить уровень ведения журнала MSAL без необходимости перестроить приложение.

Дополнительные сведения о доступных уровнях журнала см. в разделе EventLogLevel .

Пример:

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

Журналирование в распределенном кэше токенов

Если вы используете сериализаторы кэша токенов из пакета Microsoft.Identity.Web.TokenCache в .NET, можно включить дополнительное журналирование кэша.

Чтобы включить ведение журнала для распределенного кэша, установите для свойства MinLevel значение Debug.

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

Дополнительные сведения см. в разделе "Реализация пользовательского поставщика ведения журнала ".

Идентификатор корреляции

Журналы помогают понять поведение MSAL на стороне клиента. Чтобы понять, что происходит на стороне службы, команда нуждается в идентификаторе корреляции. Этот идентификатор трассирует запрос проверки подлинности через различные серверные службы.

Идентификатор корреляции можно получить тремя способами:

Из результата успешной аутентификации: AuthenticationResult.CorrelationId
Из исключения службы: MsalException.CorrelationId
Путем передачи пользовательского идентификатора корреляции WithCorrelationId(Guid) при создании запроса токена.

При предоставлении собственного идентификатора корреляции используйте другое значение идентификатора для каждого запроса. Не используйте константу, так как мы не можем различать запросы.

Сетевые трассировки

Important

Сетевые трассировки обычно содержат персональные данные и учетные данные. Удалите все конфиденциальные сведения перед публикацией журналов в GitHub.

В случаях, когда подробные журналы не предоставляют достаточно аналитических сведений, можно получить сетевую трассировку с помощью таких средств, как Fiddler или mitmproxy. Вы можете настроить выбранный вами инструмент для использования в качестве локального прокси-сервера и приема трафика от устройств в вашей локальной сети, что позволит захватывать трассировки с других устройств, таких как iPhone или телефоны Android. Перед записью журналов может потребоваться конфигурация для конкретной платформы.

Если такой инструмент невозможно использовать, можно изменить HttpClient, используемый MSAL для ведения журнала HTTP-трафика. Дополнительные сведения см. в этой пользовательской HttpClient реализации с ведением журнала.

Предупреждение

Этот клиент не должен использоваться в рабочей среде и только для ведения журнала.

Пользовательский HttpClient можно добавить следующим образом:

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

Сетевые трассировки при использовании WAM

Чтобы собирать сетевые трассировки для Web Account Manager (WAM) в Windows с помощью Fiddler, необходимо выполнить несколько дополнительных действий.

Включите функцию обратного цикла AppContainer в Fiddler, щелкнув WinConfig, выбрав " Исключить все " и сохранив изменения.

Интерфейс исключения в Fiddler, показывающий все приложения в диалоговом окне WinConfig.

Включите расшифровку HTTPS, но исключите ADFS (msft.sts.microsoft.com) из расшифровки HTTPS:

Снимок экрана: параметры Fiddler, в котором показано, как настроить расшифровку HTTPS

Last updated on 2026-07-02