登录 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 包中的令牌缓存序列化程序，则可以启用额外的缓存日志记录。

若要启用分布式缓存日志记录，请将 MinLevel 属性设置为 Debug。

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

有关更多详细信息，请参阅“实现自定义日志记录提供程序 ”。

网络痕迹

Important

网络跟踪通常包含个人身份信息和凭据。在GitHub上发布日志之前，请删除任何敏感详细信息。

如果详细日志不提供足够的见解，可以使用 Fiddler mitmproxy等工具获取网络跟踪。可以将所选工具配置为本地代理，并接受来自本地网络上设备的流量，以便捕获来自其他设备（例如 iPhone 或 Android 手机）的跟踪。在捕获日志之前，可能需要特定于平台的配置。

如果无法使用此工具，则可以修改 MSAL 用于记录 HTTP 流量的 HttpClient。有关参考信息，请参阅此带有日志记录的自定义 HttpClient 实现。

Warning

此客户端不应用于生产环境，并且仅用于日志记录。

可以按如下所示添加自定义 HttpClient ：

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

使用 WAM 时的网络跟踪信息

若要使用 Fiddler 收集 Windows 上的 Web 帐户管理器（WAM）的网络跟踪数据，需要执行几个额外步骤。

通过在 Fiddler 中单击 WinConfig、选择“免除所有”并保存更改，启用 AppContainer 环回。

Fiddler 中的豁免接口，其中显示了 WinConfig 对话框中的所有应用程序。

启用 HTTPS 解密，但从 HTTPS 解密中排除 ADFS （msft.sts.microsoft.com）：

Fiddler 选项的屏幕截图，其中显示了如何配置 HTTPS 解密

Last updated on 2026-07-06