A Developer Preview of the Active Directory Authentication Library (ADAL) v2
It feels so much longer, but in fact it’s barely five months since ADAL .NET v1 hit general availability… however here we move at cloud speed, hence today we are already unveiling the developer preview of our V2!
In fact, we have quite a number of news. For details, read on!
Overview
You can try the new package by adding it to your project via the command
Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory -Version 2.5.1-alpha -Pre
As this is a major revision, with some breaking changes, we made sue to increment the major version to 2 – so that you’ll get an update only if you explicitly opt in for it. Also: as this is a preview, we live in the preview feed of NuGet – hence there’s no risk you’ll erroneously loop it in for production apps (you must use the –Pre parameter to get this package version).
Let’s see the biggest news first.
.NET and Windows Store Libraries in the Same Package
You gave us strong feedback that you’d want a single package to work with both .NET and Windows Store project types, hence we took the opportunity to unify the two packages. Now both the ADAL .NET assembly and the ADAL Windows Runtime Component (.WINMD) for Windows Store live under the same package, Microsoft.IdentityModel.Clients.ActiveDirectory.
In practice, that means that you always refer to the same package regardless of the project type you are working with – and NuGet will figure out what’s the right library for you automatically. Neat!
In the process we also refreshed the feature set of our Windows Store library, still in preview but now far closer to its release state than before (more about that below).
New in ADAL .NET
Let’s see what’s new in this preview of ADAL .NET v2.
The object model remains the same, you work with a representation of your authority (an AuthenticationContext instance) which you can use to obtain access tokens for your protected resources (via the various flavors of AcquireToken*). Hence, the best way to find the most obvious changes is to instantaite an AuthenticationContext and see if the intellisense offers any clues.
…and it most certainly does!
Async Methods
The first thing that jumps to the eye is that every flavor of AcquireToken now has an async counterpart, and then some.
Native support for async was one of the biggest asks in v1, especially for people targeting the middle tier, hence we made it a priority to add it in v2.
You might notice a new method there, AcquireTokenSilentAsync. That method is one of the async counterparts of the sync overload of AcquireToken meant to be used with public clients– it contains the keyword “silent” because the async version won’t ever pop out a UI. We know that doesn’t jibe well with the Never flag we just introduced; expect some changes in the enxt iteration as we figure out how to clarify the difference between the two in the OM (and if you have ideas please write away!).
New ExpiresOn and Refresh Heuristic
In ADAL v1 we took as a principle that clock skews and similar considerations are really between the authority and the resources, and that the client should not meddle with it. However in V1 we did get feedback that sometimes the skew caused the client to think that a token is still valid while for the resource it was already expired, forcing the client developer to implement complicated countermeasures.
Furthermore: in v1 we returned ExpiresOn as provided by the authority, that is an exact point in time in the reference frame of the authority. As a result, when ADAL verified whether a token is still valid or not, it compared a time in the authority reference frame with a time in the client machine’s reference frame. That added a further element of uncertainty, as any authority-client skew would have weighted on the validity check.
To provide a more precise validity estimate in v2, we made the following changes:
- The returned ExpiresOn is now a calculated value, of the form
Ttoken received + ExpiresIn
That eliminates from the equation any skew that might have been present between the authority and the client, given that the instant is now in the client’s reference frame.
-
We introduced a 5 minutes margin for the use of the refresh token. If we have in cache an access token that is less than 5 minutes from its ExpiresOn, and if we have a refresh token for it, we go ahead and refresh it anyway. That provides some protection from possible authority-resource clock skews, diminishing the number of times you have to handle an error situation in your own code.
The 5 minutes value is completely arbitrary, as it appears to be a common default, and it cannot be changed. Please give us feedback if you want us to make this value configurable, otherwise that’s how we’ll ship it in the GA
ADAL .NET v2 Requires .NET 4.5 and Up
Introducing all the async primitives discussed earlier changed our minimal system requirements: whereas you could run ADAL v1 on .NET 4.0, in order to run ADAL .NET v2 you’ll need .NET 4.5 and up. This was already true for many of our other libraries (JWT handler, OWIN middleware) hence we are mostly catching up here.
ADAL .NET v2 Does not Support ACS Based Flows
As mentioned here, we are working at moving the ACS capabilities to Windows Azure AD over time. Along the same lines, ACS itself did not get any new features in the meanwhile. As a result, ADAL .NET v2 does no longer support the use of ACS namespaces as authorities.
If you still need to work with ACS, you can work with ADAL .NET v1 which remains supported.
That’s Not All Yet
There are various other features we are still working on and that did not make it into this preview. If you didn’t see in this list the feature you really wanted don’t worry yet, it’s possible it will still come in the next preview refresh!
In the meanwhile, please let us know what new features you do want – you would not believe how much impact you can have on prioritization by simply sending a message with your wish list
New in ADAL for Windows Store
The old AAL for Windows Store preview gets a complete refresh in this new preview. Apart from finally adopting the new name (“AAL” was still pre-//BUILD13), the biggest change is that it finally catches up with ADAL .NET v1 in the use of the rich Windows Azure AD features that came out in the meanwhile.
You can easily see that by comparing SxS the AuthenticationContext form the first preview and the one in the new WINMD:
Below I dig in some of the biggest changes, but if you simply want to play with the library we have a new sample showing the new preview in action.
Catch-up With ADAL .NET Features
ADAL .NET supports many special AD features, such as multi-resource refresh tokens, common endpoint, AuthenticationContext initialization via challenge, user and tenant information in the AuthenticationResult, overloads for common uses, and so on.
This version catches up with all of those features, compatibly with the scenarios that Windows Store applications need to tackle (that excludes token acquisition flows meant for the middle tier, for example).
New Persistent Cache
One of the most remarkable ADAL features coming to Windows Store is the fully query-able cache interface found in .NET.
.NET comes with a default in-memory cache – mostly because ADAL .NET can be used in many scenarios and there’s no obvious default choice for a persistent store. Windows Store is different though – the app sandboxing system does provide with obvious places to store tokens and natural session boundaries. For that reason, the new ADAL preview for Windows Store comes with a persistent cache directly out of the box.
We are no longer using the Vault as a store. We did that in the first preview, but it didn’t work out too well. First, administrators didn’t like the fact that tokens roamed without any chance to stop it via policies (whether the value roams is decided by your device status, e.g. if you declare it trusted and sing in using an MSA). Second, it often filled up on dev machines always at the wrong time Hence, the new cache uses the app’s isolated storage, and is of course encrypted. It worked out pretty well in our tests, but of course we’re eager to hear from you about it!
Better Capabilities Handling
The first preview always required the Enterprise Authentication capability in the app’s manifest, on the basis that we don’t know if any leg in the authentication flow will need it hence we require it just in case. However that caused the certification bar for apps to raise significantly, as very few apps can request that capability. As a result, we added a knob (“UseCorporateNetwork”) that allows you to declare that in your app you won’t use any capabilities (like integrated auth against ADFS) so that ADAL will not require it upfront.
Feedback, Feedback, Feedback!
There you have it. If you have apps and solutions which need a token from Windows Azure or Windows Server AD, then ADAL is for you and the v2 will allow you to do things which were not possible in v1, do check it out!!
As usual, the preview period is your opportunity to give us feedback and see its results very quickly – don’t miss it and have fun!