Logging in ADAL.Net

At a glance

LoggerCallbackHandler.PiiLoggingEnabled = true;
LoggerCallbackHandler.LogCallback = ((lvl, msg, isPii)  =>
{
    // Don't log personal details (such as usernames) and post them on GitHub
    // but when sending logs to the Microsoft engineers, sending more detailed logs helps 
    // debug issues
    // if (isPii) { return } 

    string messgeToLog = $"[{lvl}][{isPii}]: {msg}";     
   // Replace with the logging mechanism of your choice
    Console.WriteLine(messgeToLog); // Console is usually redirected to VS Output window
});

Correlation ID

Logs help understand ADAL's behaviour, 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:

From a successful auth result AuthenticationResult.CorrelationId From a service service exception AdalServiceException.CorrelationId You can start the auth flow by passing your own correlation Id: authenticationContext.CorrelationId = "your guid". Don't use a constant or we won't be able to differentiate requests.

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

By default, ADAL.NET logging, from ADAL.NET 3.18, does not capture or log any PII or OII. The library allows you to turn this on (See New way of logging controlling PII). By turning on PII or OII, the app takes responsibility for safely handling highly-sensitive data and complying with any regulatory requirements.

Logging

When you want to diagnose your application, and in particular the authentication part, you can enable logging. The way to do it is different depending on if you are using ADAL.NET before version 3.18, or after.

New way of logging, controlling PII (ADAL.Net > 3.18)

Now, if you really need/want to log PII to help you with debugging, you can leverage another mechanism which disables the first one:

• You can also subscribe to every message (including the ones filtered out because they contain PII information), by setting the LogCallback delegate of LoggerCallbackHandler. You will be told by the containsPii parameter, if a message contains PII or not. Note that using LogCallback will disable logging the messages through the LoggerCallbackHandler.Callback property.
• When you set the LogCallback property of the LoggerCallbackHandler static class, you can also control if you want to log PII or not by settting the PiiLoggingEnabled property. By default, this Boolean is set to false (still to help you being GDPR compliant). If you set it to true, messages will be logged twice (one which does not contain PII, for which containsPii will be false), and the second which will contain PII (and for which containsPii will be true) Finally, in any case, when PII information is logged, it's systematically hashed.

class Program
 {
  private static void Log(LogLevel level, string message, bool containsPii)
  {
   if (containsPii)
   {
    Console.ForegroundColor = ConsoleColor.Red;
   }
   Console.WriteLine($"{level} {message}");
   Console.ResetColor();
  }

  static void Main(string[] args)
  {
   LoggerCallbackHandler.LogCallback = Log;
   LoggerCallbackHandler.PiiLoggingEnabled = true;
   AuthenticationContext authenticationContext = new 
                   AuthenticationContext("https://login.microsoftonline.com/common");
   AuthenticationResult result = authenticationContext.AcquireTokenAsync("<clientId>",
                                  "<resourceId>",
                                  new Uri("<ClientURI>"),
                                  new  PlatformParameters(PromptBehavior.Auto)
    ).Result;
  }
 }

Legacy way of logging (ADAL < 3.18)

In ADAL.NET before ADAL.NET 3.18, to log information, you need to create a class implementing the IAdalLogCallback interface. This interface has only one method, Log, which takes as parameters:

• The LogLevel enumeration (Information, Verbose, Warning, Error)
• The message to log

The legacy way of logging information was by setting an instance of this class implementing IAdalLogCallback to the Callback properties of the LoggerCallbackHandler static class. In versions of ADAL prior to 3.18, ADAL.NET used to log all the information, including secrets, and Personally Identifiable Information (PII). If you are using ADAL > 3.17.2, no PII will ever be logged through the IAdalLogCallback any longer. We made this change to help you being GDPR compliant out of the box.

class MyLogger : IAdalLogCallback
 {
  public void Log(LogLevel level, string message)
  {
   Console.ForegroundColor = ConsoleColor.White;
   Console.WriteLine($"{level} {message}");
   Console.ResetColor();
  }
 }

 class Program
 {

  static void Main(string[] args)
  {
   LoggerCallbackHandler.PiiLoggingEnabled = true; // No effect with IAdalLogCallback
   LoggerCallbackHandler.Callback = new MyLogger();
   AuthenticationContext authenticationContext = new 
                   AuthenticationContext("https://login.microsoftonline.com/common");
   AuthenticationResult result = authenticationContext.AcquireTokenAsync("<clientId>",
                                           "<resourceId>",
                                           new Uri("<ClientURI>"),
                                           new  PlatformParameters(PromptBehavior.Auto)
    ).Result;
  }
 }

How to disable logging in ADAL

In ADAL V3, to disable logging: LoggerCallbackHandler.UseDefaultLogging = false;

In ADAL V2, to disable logging: AdalTrace.LegacyTraceSwitch.Level = TraceLevel.Error;