Active Directory Authentication Library (ADAL) v2 for .NET/Windows Store/Windows Phone–General Availability!

Today it is my honor and privilege to announce the general availability of ADAL v2 for .NET, Windows Store and Windows Phone apps!
If you want to get it, all you need to do is to enter the following from the package manager in VS:

Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory

Let’s talk about what we are releasing today.

Overview

The v2 of ADAL remains faithful to the original mission statement, as articulated in the v1 GA announcement.

The Windows Azure Authentication Library (ADAL) is a library meant to help developers to take advantage of Active Directory for enabling client apps to access protected resources.

V2 also maintains the same high level primitives for modeling the entities that come into play when dealing with clients, authorities and protected resources.

Apart from some implementation details (more about those differences below), you can pretty much read the v1 post and most of that will still apply.

What changes is the scope of the library: simply put, with ADAL v2 you can do more.
You can target more project types, you have more authentication flows to choose from, you have more control over how authentication takes place and on token lifetime management.

The best way to learn about it is to play with our extensive samples collection on GitHub, but for your convenience I will list the highlight below.

What’s New Since ADAL v1

Let me be clear upfront about a very important point: as the major version switch suggests, v2 contains plenty of breaking changes. We didn’t take any of those changes lightly, but we have been aware from the very start that the kind of functionality we wanted to achieve would not have been possible via a purely additive update. The good news is that apart from some specific cases (.NET version and ACS, see below) a most of the v1 code will work with only need syntactic sugar adjustments, and a lot of it will run v2 as is. But without further ado, let’s get to the meat of the changes.

• Multi-targeting NuGet
  The ADAL v2 NuGet contains libraries for multiple platforms, and specifically
  • Any .NET 4.5+ project
  • Windows Store projects for tablet/pc, on any Windows Store language, from Windows 8 onward
  • Windows Store projects for Windows Phone 8.1 (see here)
• ADAL v2 requires .NET 4.5+
  ADAL v2 introduces async versions of pretty much all of its primitives. Moving to .NET 4.5 was conducive of that, and in line with the rest of our dev offering (see for example Katana 3)
• ADAL v2 no longer supports ACS
  We have been upfront about how Azure Active Directory is the future of ACS: this release is very much in line with what you’ll read in that post. If your app requires ACS, sticking to v1 is the way to go.
  The good news is integrating ACS in v1 forced us to make some compromises in the object model that are no longer necessary in v2, greatly enhancing clarity and predictability.
• New Authentication Flows
  ADAL v1 supported user authentication via browser dialog (backed by the OAuth2 authorization code grant for native clients, but given that ADAL is not a protocol library you are not supposed to depend on that that ), via app credentials (key and X.509 certificate, client credentials flow – as above), via authorization code (for service side flows and confidential clients) and via direct use of a refresh token as a manual fallback.
  Since then, Azure Active Directory added a number of new flows – which are very to use with ADAL v2. Namely:
  • Direct use of username/password credentials
    Basically the resource owner grant for managed tenants, and a protocol composition for federated ones that I won’t detail here because it is an implementationd etail you should not depend on anyway. This was close to the top of the feature requests, to enable testing and various other workloads. It is a powerful new flow, but has also important limitations and should be used sparingly. See this for details.
  • Windows Integrated Auth (WIA) for federated tenants
    ADAL v1 did take advantage of WIA via browser popup, but it wasn’t as easy as WIA should be. In v2 we made it very straightforward. See this for details.
  • On Behalf Of
    At the IETF there is a very nice draft specification that, I quote, “defines how to request and obtain Security Tokens from OAuth Authorization Servers, including enabling one party to act on behalf of another”. Without going too much in details, this basically enables one confidential client (web app, etc) to request a token for acting on behalf of the caller (the user of the web app). The advantage (and drawback) of this lies on the fact that the token can be acquired without risking to show any UX, as it is instead the case for authorization code flows.
    Long story short, Azure AD supports that flow – and ADAL v2 for .NET does, too. You can find a detailed sample here.
• Better support for middle tier workloads
  This applies only to the .NET part, of course (Windows Store apps don’t run as server apps). Whereas ADAL v1 was skewed toward native clients, ADAL v2 is more server-side friendly – for example, in v1 AcquireTokenByAuthorizationCode did not use the cache at all, while in v2 it does. That makes server side code significantly easier to write.
• Completely redesigned token cache model
  V2 introduces a brand new cache model, which offers many important advantages in respect to v1. You can read about it in details here, but just to mention few highlights:
  • Suitable for being used in server side apps, which might scale to very large numbers of users and associated tokens
  • Much easier to implement custom cache repositories on arbitrary storage technologies, thanks to a model that focuses on persisting and retrieving the cache as a whole
• Persistent token cache available out of the box for Windows Store apps (both tablet/pc and Windows Phone)
  The Windows Store flavors of ADAL can count on the app sandboxing offered by the Windows Runtime for saving acquired tokens in locations that are accessible only by the originating app. That means that if you use ADAL you don’t need to do anything for remembering tokens between runs and shutdowns of your apps, ADAL will store them for you so that your users will be prompted as seldom as possible.
  Note that .NET still defaults to an in-memory only OOB implementation, but per the above changing it to a persistent store is trivial.
• Richer representation of authentication outcomes
  ADAL v2 provides more info than v1 in AuthenticationResult: unique identifiers, the id_token in its entirety when present, password expiration info, and so on. The AcquireToken* primitives have been extended to take advantage of the extra info, so that for example you can either indicate that you want a token for a particular user by passing v1’s human readable ID or the newly surfaced unique id.

There are many more improvements that are harder to classify, like an improved error management system, tracing, rationalization of the order of parameters, new ways of controlling the authentication experience, rationalization of classes used to describe the application and (new) user credentials, and more.

My favorite meta-feature is that starting from v2 ADAL for .NET/Windows Store/Windows Phone is fully open source and ready for your contributions! You can read more details about it here.

What’s New Since v2 RC

We did make a couple of relatively minor changes from ADAL RC. Given that at least in one case they have the potential for breaking code based on RC, it’s important to call them out here.

• For Windows Store (tablet/pc and phone) only: All the AcquireToken* overloads that were not specifying a returnURI, are gone.
  Those overloads defaulted to the system assigned ms-app://<SID> one (as the WebAuthenticationBroker (WAB) does when you don’t specify a URL) activating the WAB “SSO mode”.
  The dev team thought that those weren’t clear enough. The way in which you do use the WAB’s SSO mode now is by passing the ms-app://<SID> URI explicitly, or by passing null.
• We now offer you a handy method you can use when implementing authorization code flows on web applications – it helps you to build an authorization request based on the tenant, clientid, resource and all the info you’d normally have to collate by hand in such flows for web applications. The method is named GetAuthorizationRequestURL

Please note, the source of ADAL is now in a new location – https://github.com/AzureAD/azure-activedirectory-library-for-dotnet –  in the same org housing all the other OSS libraries from the Azure AD team.

Thanks

We unveiled the first preview of v2 at the end of February, released an update in June, published the RC in July and finally RTM’ed today. That’s just a bit north of 6 months in total, less than half the time we took to get to the GA of ADAL v1 despite a far larger surface area. We are definitely learning how to work at cloud speed even when it comes to our libraries.
If I can say so myself, I think that the engineering team did a fantastic job with this version. As Azure AD get on the critical path of more and more services, the list of customers and partners (inside and outside of Microsoft) grows longer every day and the number of requirements expands accordingly: making everybody happy while still shipping so quickly is no small feat. Big, BIG Kudos to Afshin, the main force behind ADAL’s development; to Rich, Kanishk and the entire dev team; to Sri, Anand R, Anuj and the test team; and to Danny, latest addition to the DevEx PM team and already samples developer extraordinaire! You guys are outstanding, and I am honored to work with you

Before I send the cheesy-ometer off scale, let me add that a lot of credit for this actually goes to YOU, the application developer trying to make sense of all this scary identity stuff.
Your feedback, punctually delivered at each and every preview, led our hand on features prioritization and programing model adjustments. Your questions in emails, forums, StackOverflow, tweets and blog comments kept us honest when something wasn’t easy as it could have been, or occasionally even off track. My hope is that now that ADAL is fully open source we will be able to collaborate even more closely and do an even better job in delivering the product you want.
The desire to help you to be productive with Active Directory and the services that depend on it is what inspired us. Of course we aren’t done yet – planning for the next wave already started: but it is my personal hope that what we are releasing today will really make a positive difference for you, making your life easier when connecting to the next generation of services.

Happy coding!