Hi folks, today I am happy to announce that the version 3 of our authentication library ADAL .NET v3 is generally available. ADAL .NET v3 introduces important new features, such as cross platform development via Xamarin, which will help you to easily harness the power of Azure AD and the Microsoft cloud API – no matter what OS you are targeting.
To walk us through the salient features of this release I invited back Vittorio, a Program Manager from the developer experience team.
As always, we welcome your feedback.
Director of Program Management
Microsoft Identity Developer Platform
ADAL .NET v3 is finally ready to power your apps in production! Thanks to the new Xamarin integration features you can now write your application once, and run it on iOS, Android and Windows – ADAL v3 helps you to address your authentication needs in a single place and reuse it across all platforms.
In this post I will list the most salient news and features.
What’s new in ADAL .NET v3
ADAL .NET v3 has been refactored to extend the range of platforms it can reach. Namely, with v3 you can target:
- .NET 4.5+ applications: WPF apps, console apps, code behind of ASP.NET 4.6 web apps and API, etc etc
- UWP apps (Windows 10 and Windows 10 Mobile)
- Windows Store apps
- Xamarin iOS and Android apps
- Xamarin Forms apps
- [still preview] .NET Core apps
(note, Windows Phone is no longer supported in ADAL v3. If you need WP8.1 support, please keep using ADAL v2.x).
That’s a pretty large collection! We were able to achieve this by pivoting from Windows Runtime Components, the component technology we used in v2, and .NET portable classes. If you peek inside ADAL .NET v3 NuGet, you’ll see the following:
The idea is that when you add a NuGet reference to ADAL, the NuGet system will pull in specific assemblies depending on your project type. For example, if you are building a portable class, you’ll get netcode45 or dnxcore50. If you are building a Xamarin iOS project, however, you’ll end up with both the netcore45 assembly and the platform-specific Xamarin.iOS10 assembly.
The primitives you use for working ADAL are largely unchanged – they are the familiar AuthenticationContext, AcquireToken*, AuthenticationResult and the like. However the surface has been adjusted to accommodate the fact that your code might now be running on widely different platforms – with different ways of prompting the user, different storage technology for token caches, and so on. Here there’s how we achieve adaptive behavior across platforms.
AcquireToken* now accepts a new parameter, an interface named IPlatformParameters. That interface has a concrete implementation, PlatformParameter, for all the supported platforms. The main purpose of PlatformParameters is to carry a reference of the parent UX element from which you want to trigger the authentication experience: that helps ADAL to determine at runtime whether it should prompt the user using iOS, Android, Windows Store or Windows desktop experiences. The subdivision in interface and concrete classes allows you to maximize code reuse: you can put most of your authentication logic in a portable class, where you use the IPlatformParameter – and all you need to do for leveraging that from platform specific projects is to pass in the corresponding PlatformParameters platform specific implementation. Let me give you a practical example.
The main ADAL sample demonstrating how to work with Xamarin can be found here. It is a simple application, which allows you to query the directory to find basic information about a user.
The solution structure follows the pattern introduced earlier: there is a portable class project containing the bulk of the authentication logic, and platform specific projects (in this case for desktop, UWP, iOS, Android) implementing the experience (note, Xamarin Forms is also supported. See here for hints on how to use it).
If you expand the references folder for the portable class library and any of the platform specific projects, you’ll observe the assemblies distribution typical of the pattern.
The portable library refers to the portable ADAL assembly; the platform specific project refers to the portable library, and the ADAL PCL & the platform specific assembly.
The portable class library project contains some basic token acquisition logic. The interesting parts are highlighted below.
public static async Task<List<User>> SearchByAlias(string alias, IPlatformParameters parent)
authResult = await authContext.AcquireTokenAsync(graphResourceUri,
clientId, returnUri, parent);
The call to AcquireTokenAsync looks like the good ol’ AcquireTokenAsync in ADAL 2.x, except for the new parameter passing in the IPlatformParameters.
Let’s once again pick the Android project as the representative of what happens in platform specific project. The directory searching functionality is implemented in MainActivity.cs. Here there’s the code used to trigger the search.
List<User> results = await DirectorySearcher.SearchByAlias(searchTermText.Text, new PlatformParameters(this));
The PlatformParameters instance passed here is the Android specific implementation of IPlatformParameters, taking in input the current activity. This allows ADAL to dynamically determine what logic to invoke for displaying prompts and access storage in platform specific fashion. iOS has similar code in its viewcontroller, Windows in its XAML page, and so on.
The Nuget refactoring and the IPlatformParameters are the main structural differences in respect to ADAL 2.x. There are many more news, of course! You can find a list of the differences in the changelog reported in the releases section of ADAL .NET’s github repo – however you’ll likely have more fun by experimenting with the samples!
Danny Strockis from our PM team worked hard to port most of the .NET samples (a staggering 35 of them, at the moment) to use ADAL v3. Among those you’ll find a number of samples showing off the brand new features ADAL v3 introduces, such as the aforementioned Xamarin sample and the device profile sample (introduced here – and which happens to also run on Linux and Mac!).
Note: if for some reason you need to stick with ADAL v2.x for a little longer, and you need to access the version of the samples using ADAL v2.x, you can go to the releases section of the sample repo and select the release labeled ADAL v2. For example for the desktop apps sample in https://github.com/Azure-Samples/active-directory-dotnet-native-desktop/ you can access the ADAL v2.x version by navigating to https://github.com/Azure-Samples/active-directory-dotnet-native-desktop/releases/tag/v2.X.
ADAL v3 and .NET Core RC2 support
Earlier this week the ASP.NET and .NET teams released the RC2 of .NET Core and ASP.NET Core.
ADAL v3 is now GA, hence its NuGet is in the stable nuget.org feed – it would be odd to reference to prerelease bits, hence the stable ADAL v3 package does NOT work with .NET Core. We’ll be releasing a version of ADAL working .NET Core RC2 in the coming weeks.
ADAL v3 and MSAL
You will recall that few weeks ago, during //build/, we announced the preview of MSAL – a new authentication library that works with the v2 authentication endpoint of Azure AD (supporting both work & school accounts and Microsoft Accounts, or MSAs) and with Azure B2C. MSAL works exclusively with those new endpoints, and cannot be used for obtaining tokens from the current organizations-only Azure AD v1 endpoints. Furthermore, MSAL does not work with ADFS – while ADAL v3 does (and in fact, we expanded support for the scenarios offered by ADFS in Windows Server 2016).
Hence, choosing what library to use in your project is easy. If you need to talk with services that only accept tokens issued by organizations-only Azure AD v1 endpoints, such as the Azure management API; if you need to implement topologies not yet supported by the new endpoints (such as exposing your own API to other developers, consuming 3rd party API, etc); if you need to connect with ADFS directly, use ADAL v3. If you want to experiment with the Microsoft graph, work on scenarios where business and consumer identities seamlessly blend, or try new features (such as incremental consent), the MSAL will be the right fit for the job.
Well, there you have it. ADAL v3 unlocks scenarios and use cases that weren’t possible with ADAL v2, unlocking the full potential of cross platform development without compromising on the ease of use you’ve come to know and love. We want to thank you for the tons of useful feedback you gave us during the preview period. Please keep your feedback coming, and thank you for using our services!
Principal Program Manager
Microsoft Identity Division