adalnet4 0 preview

ADAL.NET 4.0.0-preview and MSAL.NET 2.0.0-preview just released

We are excited to announce the release of ADAL.NET 4.0.0-preview and MSAL.NET 2.0.0-preview. These releases are preview versions of major versions of ADAL.NET and MSAL.NET and they introduce new and interesting features. In particular, ADAL.NET and MSAL.NET now share the same token cache. As with many preview versions, these releases also introduce breaking changes; however, for ADAL.NET, updating the NuGet package and rebuilding your app will work for most cases. We encourage you to try out the preview releases and send us feedback. We'll be releasing a non-preview version of ADAL.NET 4.0.x in the coming weeks and we'll continue to work on MSAL.NET until it reaches general availability in the coming months.

In this blog post, and the two companion articles Changes in ADAL.NET 4.0.0-preview and Changes in MSAL.NET 2.0.0-preview you'll learn:

• How a common token cache will help you migrate your applications from ADAL.NET to MSAL.NET
• How we are modernizing the platforms supported by ADAL.NET and MSAL.NET, dropping support for Windows 8.1 and Windows Phone 8.1, but supporting .NET core and Windows 10 explicitly in MSAL.NET, which are binary breaking changes for ADAL.NET
• What's new in MSAL.NET, as well as the changes (breaking or not), replacing Users by Account and how semantics are better defined
• How you can migrate your MSAL.NET 1.x app to MSAL.NET 2.x
• What's coming next in MSAL.NET

Convergence of Azure AD v1.0 and Azure AD v2.0

What were your choices so far?

ADAL.NET and MSAL.NET are both .NET libraries that you use to acquire tokens to access protected Web APIs. Until recently ADAL and MSAL were part of two distinct technology stacks, and you had to make a choice:

• ADAL targets the Azure AD v1.0 endpoint, signing users with their work and school accounts, and you had to create and manage the application in the Azure portal
• MSAL targeted the Azure AD v2.0 endpoint, signing users with their work and school accounts or Microsoft personal accounts. You had to create and manage your application in a different portal: the application registration portal

To understand more about these technology stacks, related to ADAL.NET and MSAL.NET, see https://aka.ms/msal-net-register-v2-app.

What is changing and why?

At Microsoft Build 2018 (To sign in and beyond: Doing more with your applications and Azure AD), we announced that we are working on converging both technology stacks at every level:

• Azure AD protocol level (an app is an app, there is no longer the notion of a v1.0 app and a v2.0 app),
• at the portal level: we are delivering a unified experience to register and maintain apps in the Azure portal,
• and at the library level, MSAL will be the solution of choice. The goal is eventually that you don't need to choose: you just pick up MSAL, use the Azure portal and everything just works. But you would also be free to stay with ADAL if you don't need the additional features that MSAL will support moving forward, or migrate to MSAL at your own pace. This release is the first step of this convergence effort for the .NET client libraries. It will be followed by more releases of MSAL.NET in the coming weeks as we complete feature parity between ADAL.NET and MSAL.NET.

Common token cache scenarios

In the future, you'd want to use MSAL in your applications, instead of ADAL. However, if you have applications leveraging ADAL.NET and running in production, when upgrading, you probably don't want to force your users to re-sign-in. To preserve the single-sign-on (SSO) state, the new versions of ADAL and MSAL share the same token cache, are capable of reading the ADAL 3.x token cache and are capable of writing the ADAL 3.x token cache in addition to the new cache format (named unified cache). This means that:

• You can convert an ADAL.NET 3.x application to ADAL.NET 4.x and preserve the SSO state.
• You can convert an ADAL.NET 3.x or an ADAL.NET 4.x application to MSAL.NET 2.x and preserve the SSO state.
• You can have your users run side by side the ADAL.NET 3.x and ADAL.NET 4.x or MSAL.NET 2.x applications and share the SSO state. This is especially important for Web App and Web API in a farm of servers that need to run without interruption. In that case, you'll upgrade your apps progressively, as they need to keep sharing the security tokens.
• Finally, on iOS, you can even have native iOS applications and Xamarin iOS ADAL and MSAL applications share the same token cache provided you set the key chain security group (more about that below).

Changes in ADAL.NET 4.0.0-preview

The changes in ADAL.NET are described in details in Changes in ADAL.NET 4.0.0-preview. As a summary:

• ADAL.NET 4.x can now read the MSAL 2.x unified format cache in addition to the ADAL.NET 3.x token cache.
• ADAL.NET 4.x can also share the token cache with ADAL and MSAL for objective C on iOS.
• Despite the major number being bumped-up from 3 to 4, ADAL.NET 4.0.0-preview only has platform and binary breaking changes: it no longer supports Windows and Windows Phone 8 and 8.1, but adds support for Windows 10 applications (through the uap10.0 platform)

Changes in MSAL.NET 2.0.0-preview

The changes to MSAL.NET are described in details in Changes in MSAL.NET 2.0.0-preview. To summarize:

• You can now share the token cache between ADAL 3.x, ADAL 4.x, and MSAL 2.x applications, and also between Xamarin.iOS and native iOS
• You can now decide to use an embedded web browser on Xamarin.iOS and Xamarin.Android applications instead of the system browser which is used by default.
• The supported platforms were modernized, dropping support for Windows and Windows Phone 8/8.1, and supporting .NET core explicitly
• IUser was replaced with IAccount and the methods to get an IAccount are now asynchronous. These are breaking changes, but we provide you with guidance on the impact on your MSAL 1.x applications

Do you want to migrate from ADAL.NET to MSAL.NET ?

For a deep dive on the differences between ADAL.NET and MSAL.NET, see https://aka.ms/adal-net-to-msal-net.

We also started working on a sample to help you migrate: https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2

What's coming next in MSAL.NET?

This release is a first step. We'll release more features soon in MSAL.NET 2.x to bridge the gap with ADAL.NET, including:

• Support for Integrated Windows Authentication.
• Support for the Username / Password flow. Even if we don't recommend it, we recognize that this flow is still needed in a number of scenarios.
• Support for the Device Code Flow, enabling users to sign-in on devices without a browser.

To see the list of features we will be delivering, see https://aka.ms/msal-net-feature-gap and https://aka.ms/adal-net-roadmap

Send us feedback

We'd love to hear from you about these major release previews. To reach us:

• Ask questions on Stack Overflow using the ADAL tag or the MSAL tag
• Use GitHub Issues on the ADAL.Net or MSAL.NET open source repository to report bugs or request features
• Use the User Voice page to provide feature recommendations and/or feedback.