Logging

Logs

ADAL relies heavily on logging to diagnose issues. It is highly recommended that you set an ADAL 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 ADAL logging and incorporate it in your own application's logging:

/*!
    The LogCallback block for the ADAL logger
 
    @param  logLevel        The level of the log message
    @param  message         A short log message describing the event that occurred, this string will not contain PII.
    @param  additionalInfo  A longer message that may contain PII and other details relevant to the event.
    @param  errorCode       An integer error code if the log message is an error.
    @param  userInfo        A dictionary with other information relevant to the log message. The information varies,
                            for most error messages the error object will be in the "error" key.
 */
typedef void (^LogCallback)(ADAL_LOG_LEVEL logLevel,
                            NSString *message,
                            NSString *additionalInfo,
                            NSInteger errorCode,
                            NSDictionary *userInfo);

Otherwise ADAL outputs to NSLog by default, which will print messages on the console.

Example Log Message

The message portion of ADAL iOS are in the format of ADALiOS [timestamp - correlation_id] message

ADAL [2015-06-22 19:42:53 - 1030CB25-798F-4A6F-97DF-04A3A3E9DFF2] ADAL API call [Version - 2.1.0]

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

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

By default, ADAL telemetry does not capture or log any PII or OII. The library allows app developers to turn this on through a setter in the ADLogger 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 `ADLogger` does not capture any PII or OII

// PII or OII will be logged
[ADLogger setPiiEnabled: TRUE]

// PII or OII will NOT be logged
[ADLogger setPiiEnabled: FALSE]

Logging Levels

• ADAL_LOG_LEVEL_NO_LOG (Disable all logging)
• ADAL_LOG_LEVEL_ERROR (Default level, prints out information only when errors occur)
• ADAL_LOG_LEVEL_WARNING (Warning)
• ADAL_LOG_LEVEL_INFO (Library entry points, with parameters and various keychain operations)
• ADAL_LOG_LEVEL_Verbose (API tracing )

To set the logging level in your application call +[ADLogger setLevel:]

[ADLogger setLevel:ADAL_LOG_LEVEL_INFO]