API Changes

A number of APIs were changed with 2.1 to make the Objective-C API better match the .NET interface

ADUserIdentifier

ADUserIdentifier allows developers to specify how they want the user id string to be validated. When signing in a user for the first time and you aren't sure what exactly their UPN is going to be we recommend using a OptionalDisplayableId and then recording the userID that comes back with the token for future token requests.

Token Cache

The token cache APIs have been restricted to prevent developers from taking dependencies on internal implementation details of the cache. Furthermore commonly abused APIs like removeAll have been removed. If you need to traverse the cache outside a acquireToken call you should use the ADKeychainTokenCache class on iOS and ADTokenCache on Mac OS X.

ADLogger

The ADLogger callback has been modified to clarify the intention of each of the strings, and provide more data in the userInfo dictionary for applications looking for more targeted telemetry.

/*!
    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);

Log statements have been improved across the board, with a lot more useful logging coming through the "message" string at the INFO level. Logging is vitally important for diagnosing issues that occur in the library and we highly recommend all developers take advantage of the log callback.

ADWebAuthController

The ADAuthenticationBroker class from 1.x has been renamed to ADWebAuthController to avoid confusion with brokered authentication via Azure Authenticator. The APIs themselves have been renamed to reduce confusion as well and notifications have been added for developers wishing to observe the web flow in ADAL. Note that those notifications only work when the authentication flow is happening in process (not via Authenticator).

Mac OS X Support

ADAL now officially supports Mac OS X in both 32 bit and 64 bit flavors, from the same branch as iOS. To underscore this the library is now simply "ADAL" in the project name, CocoaPod name and framework name. Please switch to the 'ADAL' CocoaPod if you're using CocoaPods.

Cache Persistence

While Keychain is similar between iOS and OS X, the level of data partitioning is not. In our previous attempts we discovered that trying to provide a generic keychain cache implementation on OS X that would simultaneously protect an application's tokens while also not causing conflicts between applications was not feasible. For that reason on OS X we require developers to provide a ADTokenCacheDelegate for managing persisting the cache.

Brokered Authentication and 3rd Party Conditional Access Support

ADAL 2.1 is the first version to publicly support conditional access in 3rd party applications via Azure Authenticator. See the ReadMe for more information on configuring your application for brokered authentication.