Logging

Logging in MSAL

MSAL apps generate log messages that can help diagnose issues. An app can configure logging with a few lines of code, and have custom control over the level of detail and whether or not personal and organizational data is logged.

Create a logging callback:

void MyLoggingMethod(LogLevel level, string message, bool containsPii)
{
    Console.WriteLine($"MSAL {level} {containsPii} {message}");
}

Then provide the callback to WithLogging method when creating the PublicClientApplication or ConfidentialClientApplication:

var app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
          .WithLogging(MyLoggingMethod, LogLevel.Info,
                       enablePiiLogging: true, 
                       enableDefaultPlatformLogging: false) // the platform logger for .NET FW / .NET Core is EventSource
          .Buid();

Important: exception messages are not captured if enablePiiLogging is set to false (PII = Personally Identifiable Information). If you need to contact support, please try to send Verbose logs with PII. Do not post PII logs on GitHub!

Example of logs - logs with PII and logs without PII.

Network traces

Important: Network traces typically contain PII information. Please remove sensitive details before posting on GitHub.

You can get a network trace using tools like Fiddler. If such tool is not possible to use, for example on mobile, you can modify the HttpClient used by MSAL to log the HTTP traffic. See example HttpClient with logging here (this should not be used in production, but only for logging). Custom HttpClient can be added as following:

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

Correlation ID

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

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

The correlation ID can be obtained in three ways:

1. From a successful authentication result - AuthenticationResult.CorrelationId.
2. From a service exception - MsalServiceException.CorrelationId.
3. By passing a custom correlation ID to .WithCorrelationId(Guid) builder method when building a token request. Use a different ID value for each request. Don't use a constant or we won't be able to differentiate requests.

Windows Broker (WAM) logging

If you are using WAM, collect the MSAL verbose logs first. If more investigation is needed, follow: https://aka.ms/wamhot - this will use a tool created by Office that collects WAM traces. You can use the tool with any program.

Windows Broker (WAMnetwork traces

If using Fiddler, please configure it as if capturing from an UWP app:

1. Enable AppContainer loopback in Fiddler UI -> WinConfig -> Exempt All -> Save Changes.

2. Enable HTTPS decryption, but exclude AD FS from HTTPS decryption:

Full WAM logs

Go to http://aka.ms/icesdptool, which will automatically download a .cab file containing the Office Sign-in and Authentication Diagnostic tool. Run the tool and repro your scenario, once the repro is complete. Finish the process.

Note: If do not want to give Fiddler traces simply reject the certificate requests that will pop up.

The wizard will prompt you for a password to safeguard your trace files. Please provide a password. You can enter "1234" as the password (aka the Default password). However, if for personal reasons you decide to enter a different password, please ensure that you communicate that separately to the team doing the investigation downstream.

Finally, open the folder where all the logs collected are stored. It is typically in a folder like %LOCALAPPDATA%\ElevatedDiagnostics<numbers> Typing "%LOCALAPPDATA%" in your file explorer will take you to the correct location Send the latest.cab, which contains all the collected logs, file to us.

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 enable this by setting enablePiiLogging to true in WithLogging builder. By turning on PII or OII, the app takes responsibility for safely handling highly-sensitive data and complying with any regulatory requirements, in particular GDPR.