Changes adalnet 4.0

ADAL.NET v4 is now GA (2018, October 19th)

ADAL.NET 4.0.0-preview was released on 2018, August 28th, along with MSAL.NET 2.0.0-preview. See details in the blog post

Changes in ADAL.NET from 3.x to 4.x

ADAL.NET and MSAL.NET are multi-platform, running on .NET Framework, .NET Core, UWP, and also Xamarin.iOS and Xamarin.Android. We have simplified and modernized the platforms supported by ADAL.NET and MSAL.NET.

Changes in ADAL.NET's structure

	ADAL.NET 3.19.8	ADAL.NET 4.3+
Supported Platforms	Net45 (.NET Framework 4.5) NetStandard1.1 NetStandard1.3 NetCore45, (Win8 Store) MonoAndroid7 (For Xamarin.Android) Xamarin.iOS10 Portable-net45+win (PCL, but it's better to use NetStandard 1.1 anyway for PCL libraries)	Net45 (.NET Framework 4.5) Netcoreapp1.0 (.NET Core) NetStandard1.3 Uap10.0 MonoAndroid8.1 (For Xamarin.Android) XamariniOS10 (For Xamarin iOS)
DLLs	Two DLLs for each platform: Microsoft.Identity.Model.Clients.ActiveDirectory.dll and Microsoft.Identity.Models.Clients.ActiveDirectory.Platform.dll, which only contained type forwarding to be binary compatible with earlier versions of ADAL.NET 3.x	One DLL for each platform: Microsoft.Identity.Model.Clients.ActiveDirectory.dll

No significant breaking changes in ADAL.NET

There are no major breaking changes in ADAL.NET public API beyond the changes in the platforms, the removal of the assembly named Microsoft.Identity.Models.Clients.ActiveDirectory.Platform.dll (which was only here for binary compatibility in the ADAL 3.x series) and the removal of a type that should not have been public in the internal sub namespace (WebBrowserNavigateErrorEventHandler in the net45 platform, Resource in the Xamarin.Android platform). We bumped-up the major version from 3. to 4. because of these breaking changes (mostly binary).

Better Authority validation

ADAL.NET 4.x is also less forgiving than ADAL 3.x when setting the authority in the constructor of AuthenticationContext. Valid authorities should be, in the case of Azure AD v1.0:

• https://login.microsoftonline.com/{Guid}, where the Guid is the tenant ID
• https://login.microsoftonline.com/domainName, where the domain name is a domain associated with your tenant
• https://login.microsoftonline.com/common which, in the case of ADAL.NET means any Azure AD tenant (note that the meaning is different in MSAL.NET)

It cannot be https://login.microsoftonline.com/common/OAuth2/endpoint even if this for could have been wrongly accepted in ADAL 3.x

Addition to ADAL.NET's public API

Enabling SSO between ADAL V3 and ADAL V4 / MSAL V2

If you only want to migrate from ADAL V3.x to ADAL V4.x, you should not need to change any code. However, if you have a desktop application and you want to ensure that your ADAL V3/ V4 application also shares the token cache with an MSAL V2 application, you might want to update your implementation of the token cache custom serialization. ADAL V4, in addition to the pre-existing Deserialize(byte[] adalState) method, introduces methods that enable you to serialize and deserialize the cache:

public class TokenCache
{
 ...
 public void DeserializeAdalAndUnifiedCache(CacheData cacheData);
 public CacheData SerializeAdalAndUnifiedCache();
 ...
}

with CacheData being a new data structure, shared by both ADAL 4.x and MSAL 2.x, and containing blobs corresponding to the token cache in both the ADAL V3 format, and the new Unified cache format, which is shared between ADAL and MSAL and across platforms (See next paragraph for an example for iOS)

namespace Microsoft.Identity.Core.Cache
{
    public class CacheData
    {
        public byte[] AdalV3State { get; set; }
        public byte[] UnifiedState { get; set; }
    }
}

In ADAL.NET V3, you could customize token cache serialization in desktop applications, serializing to a file, like what is shown in Custom serialization in legacy format (ADAL V3 compatible)

In ADAL.NET V4, you can now still have compatibility with the ADAL.NET V3 cache, but also add serialization with the new Unified cache format (which is really a json blob), bringing compatibility with MSAL.NET V2.x and being common on all platforms. The code to write is then slightly different as you will serialize both cache representations to two different files. Some ready to reuse code for .NET framework applications is available from Custom serialization in dual format (ADAL V3 compatible and Unified cache).

Note that on mobile platforms (UWP, Xamarin.iOS, Xamarin.Android), you will benefit automatically from the token cache sharing between ADAL and MSAL as the library handles the serialization to the container of choice of the platform (respectively isolated storage, iOS key chain, and Android shared preferences)

Enabling SSO between apps on Xamarin.iOS

On the iOS platform, the unified token cache format and location is even shared with ADAL.iOS and MSAL.iOS, therefore enabling SSO between a native iOS application (leveraging ADAL.iOS or MSAL.iOS) and a Xamarin ADAL.NET or MSAL.NET application. This is something that some of you requested in order to move legacy native applications to Xamarin, without losing the SSO state. For this, in ADAL.NET, in the Xamarin.iOS platform, AuthenticationContext has a new property named KeychainSecurityGroup. This Xamarin iOS specific property enables you to direct the application to share the token cache with other applications sharing the same keychain security group. If you provide this key, you must add the capability to your Application Entitlement. For more info, see Enable token cache sharing across iOS applications.

Note: This API may change in a future release to align better with the ADAL.iOS (native) library.

AdalError

The AdalError class now has new error messages in every platform:

• BrokerRedirectUriIncorrectFormat is now thrown on Xamarin.Android when you have set the UseBroker parameter of the PlatformParameters to true, but the redirect URI for your application is not the one expected by the broker (scheme://{package name}{signature for package name}). For more information, see Leveraging brokers on Android and iOS
• InvalidWebBrowserType and InvalidWebPageResponse are thrown when the web page returned by the STS is not the expected one.

ADAL.NET now supports ADFS 2019

You can now use ADFS 2019 including device code flow from ADAL.NET 4.3.0