Logging

Logging

Microsoft Identity Web integrates with the logging available in ASP .NET Core. Starting in Microsoft Identity Web v1.4.1, the MSAL .NET logs are also enabled to assist with troubleshooting and understanding any issues that may occur during token acquisition.

How do I subscribe to the middleware events?

See the web API troubleshooting page.

How do I enable the MSAL .NET logs?

To enable the MSAL .NET logs, just explicitly enable the Microsoft Identity Web logs, for example, in appsettings.json:

"Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Identity.Web":  "Information"
        }
...

Adding this line "Microsoft.Identity.Web": "Information" will enable the MSAL .NET logs at the "information" level.

MSAL .NET provides four log settings:

• Info - recommended setting for generating key parts of the authentication flow in MSAL .NET. For debugging and development. Use with caution in production due to high volume.
• Verbose - contain the most detailed messages. For debugging and development. Use with caution in production due to high volume.
• Warning - for abnormal or unexpected events. Typically includes conditions that don't cause the app to fail.
• Error - for errors and exceptions.

These log levels are mapped as follows in Microsoft.Identity.Web:

ASP .NET log level	MSAL .NET log level
Microsoft.Extensions.Logging.LogLevel.Information	Microsoft.Identity.Client.LogLevel.Info
Microsoft.Extensions.Logging.LogLevel.Debug	Microsoft.Identity.Client.LogLevel.Verbose
Microsoft.Extensions.Logging.LogLevel.Trace	Microsoft.Identity.Client.LogLevel.Verbose
Microsoft.Extensions.Logging.LogLevel.Warning	Microsoft.Identity.Client.LogLevel.Warning
Microsoft.Extensions.Logging.LogLevel.Error	Microsoft.Identity.Client.LogLevel.Error
Microsoft.Extensions.Logging.LogLevel.Critical	Microsoft.Identity.Client.LogLevel.Error

Enable PII logs

Personal Identifiable Information (PII) & Organizational Identifiable Information (OII)

By default, MSAL.NET logging does not capture or log any PII or OII. The library allows you to turn this on (See PiiLoggingEnabled below). By turning on PII or OII, the app takes responsibility for safely handling highly-sensitive data and complying with any regulatory requirements and in particular GDPR.

To enable Pii logs in Microsoft.Identity.Web, in appsettings.json in the AzureAd section include the following: "EnablePiiLogging": true,

By default, this value is set to false.

Logging in .NET Framework or .NET Core

When using the token cache serializers from Microsoft Identity Web in .NET Framework or .NET Core, you can still benefit from the detailed token cache logs by adding the following code:

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

Setting the LogLevel to Debug will provide you with the most verbose MSAL.NET and Microsoft Identity Web logs around the token cache.

Sample on using the Microsoft Identity Web token cache serializers.

Correlation ID

Logs help understand MSAL .NET's behavior on the client side.

To understand what's happening on the service side, the team needs a correlation ID. This traces an authentication request through the various back-end services.

The correlation ID can be obtained in 3 ways:

1. From a successful auth result AuthenticationResult.CorrelationId
2. From a service exception MsalServiceException.CorrelationId
3. Provide your own correlation ID (a GUID).

You can specify your own correlation ID in Microsoft.Identity.Web, in the TokenAcquisitionOptions.

For example:

public async Task<ActionResult> Details(int id)
{
 var value = await _downstreamWebApi.CallWebApiForUserAsync<object, Todo>(
    ServiceName,
    null,
    options =>
    {
     options.HttpMethod = HttpMethod.Get;
     options.RelativePath = $"api/todolist/{id}";
     options.TokenAcquisitionOptions.CorrelationId = correlationId;
    });
 return View(value);
}