Logging

Logs

MSAL relies heavily on logging to diagnose issues. It is highly recommended that you set an MSAL logging callback and provide a way for users to submit logs when they are having authentication issues.

Logging Callback

You can set a callback to capture MSAL logging and incorporate it in your own application's logging:

/*!
    The LogCallback block for the MSAL logger
 
    @param  level           The level of the log message
    @param  message         The message being logged
    @param  containsPII     If the message might contain Personally Identifiable Information (PII)
                            this will be true. Log messages possibly containing PII will not be
                            sent to the callback unless PIllLoggingEnabled is set to YES on the
                            logger.

 */
typedef void (^MSALLogCallback)(MSALLogLevel level, NSString *message, BOOL containsPII);

Example usage:

[[MSALLogger sharedLogger] setCallback:^(MSALLogLevel level, NSString *message, BOOL containsPII)
{
     if (!containsPII)
     {
          NSLog(@"MSAL log: %@", message);
     }
}];

Example Log Message

The message portion of MSAL iOS are in the format of TID = <thread_id> MSAL <sdk_ver> <OS_ver> [timestamp - correlation_id] message

TID = 551563 MSAL 0.2.0 iOS Sim 12.0 [2018-09-24 00:36:38 - 36764181-EF53-4E4E-B3E5-16FE362CFC44] acquireToken returning with error: (MSALErrorDomain, -42400) User cancelled the authorization session.

Providing correlation IDs and timestamps are tremendously in tracking down issues. The only reliable place to retrieve them is from MSAL logging.

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

By default, MSAL does not capture or log any PII or OII. The library allows app developers to turn this on through a setter in the MSALLogger class. By turning on PII or OII, the app takes responsibility for safely handling highly-sensitive data and complying with any regulatory requirements.

// By default, the `MSALLogger` does not capture any PII or OII

// PII or OII will be logged
[[MSALLogger sharedLogger] setPiiLoggingEnabled:YES];

// PII or OII will NOT be logged
[[MSALLogger sharedLogger] setPiiLoggingEnabled:NO];

Logging Levels

• MSALLogLevelNothing (Disable all logging)
• MSALLogLevelError (Default level, prints out information only when errors occur)
• MSALLogLevelWarning (Warning)
• MSALLogLevelInfo (Library entry points, with parameters and various keychain operations)
• MSALLogLevelVerbose (API tracing)

To set the logging level in your application call

[[MSALLogger sharedLogger] setLevel:MSALLogLevelVerbose];