Logging

Identity Logger (Expiremental)

MSAL.NET now takes advantage of the IdentityLogger interface to provide logging for messages (MSAL.NET 4.45.0+). This comes with the benefit of enabling one logger implementation to be sharable between our partner SDks (Identity Web, IdentityModel). In order to take advantage of this new api you will need to provide an implementation of the IIdentityLogger interface. This also enables you to change the behavior of the identity logger without having to rebuild your MSAL implementation. For example, you could configure the log level in the IsEnabled method to use a environment variable for greater flexibility during debugging.

IIdentityLogger Interface

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

IIdentityLogger Implementation

Log Level as Environment Variable

It is highly recommended to configure your code to use an environment variable on the machine to set the log level as it will enable your code to change the MSAL logging level without needing to rebuild the application. This is critical for diagnostic purposes, enabling us to quickly gather the required logs from the application that is currently deployed and in production.

See EventLogLevel for details on the available log levels.

Example:

    class MyIdentityLogger : IIdentityLogger
    {
        public EventLogLevel MinLogLevel { get; }

        public TestIdentityLogger()
        {
            //Try to pull 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);
        }
    }

Using IdentityLogger:

    MyIdentityLogger myLogger = new MyIdentityLogger(logLevel);

    var app = ConfidentialClientApplicationBuilder
        .Create(TestConstants.ClientId)
        .WithClientSecret("secret")
        .WithExperimentalFeatures() //Currently an experimental feature, will be removed soon
        .WithLogging(myLogger, piiLogging)
        .Build();

Add a log callback (Legacy)

An app also has the option to 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 with a logging callback.

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! Logs will never contain passwords or tokens, but PII logs may contain usernames, IDs etc.

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 (WAM) network 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.