ADAL 3 didn’t return refresh tokens for ~5 months… and nobody noticed

As you know, ADAL is not meant to be a protocol library. You tell us about your client app and the resource you want to access; we get the proper tokens for you from Azure AD, via few simple primitives and without burdening with nitty-gritty protocol details.

That said… that arrangement is not 100% air tight. We do occasionally leak the abstraction: for example, we use OAuth specific terminology here and there (redirect uri…); we accept protocol parameters in extraqueryparameters; and so on. When we do so, we like to think it’s never an oversight, but a deliberate decision. We usually weigh whether the convenience of providing access to lower level constructs outperforms the complexity we’d burden you with for preserving a façade… if the convenience comes out a winner, we go for it: after all ADAL is not a science experiment, it’s something meant to make your life easier.

The refresh token in the AuthenticationResults , and corresponding AcquireTokenByRefreshToken method, is one such violation. You don’t really ever need to use the refresh token from your own app code, given that ADAL caches and will automagically use it whenever you call AcquireToken and the requested token need renewing. Ssee this and this for details. In ADAL v1 that wasn’t strictly true, given that the cache was specialized for native clients and not really suited for server side use: we had to provide you with the refresh token bits – so that you could do your own arrangements on web sites code-behind or any scenario other that the supported native client case. In ADAL v2 we improved the caching infrastructure to support server side scenarios, extending ADAL’s automatic and transparent use of the refresh token to all the mid tier flows (or, if you want me to leak protocol details… for all confidential client grants). However we weren’t completely certain that this would have addressed ALL possible scenarios, so we decided to keep exposing the refresh token in our object model.

That’s when we started noticing odd things. Developers with little or no protocol knowledge, the vast majority, happily relied on ADAL to do all the session management on their behalf and blissfully enjoyed all the automatic refresh token usage I described. So did all the people who used our GitHub samples or the VS templates as starting point for their own apps. However some developers, typically the ones with some existing protocol knowledge, skipped the samples altogether and attempted to use the library only “by intellisense”: knowing that OAuth2 does use refresh tokens, assuming that ADAL uses OAuth2 and finding methods accepting refresh tokens made them conclude that responsibility of storing and using refresh tokens was on their app code. That led to tons of extra work, code structure far more complicated than necessary, security issues and reduced functionality – for example, not all of those devs knew what a MRRT is.

Thankfully the number of the developers falling in that trap was very small in comparison to the total ADAL usage, but that made us think – do we really need to keep returning the refresh token and accept it in AcquireToken? We combed through mail threads, forum posts and customer docs searching for scenarios that could not be addressed by ADAL’s automatic usage of the refresh token – and found none. On April the 22nd we built a NuGet for ADAL v3.x with all signs of refresh tokens removed from ADAL’s programming surface, then pushed it out on NuGet.org.

Five months later, things seem to be going still pretty well. It is not entirely true that absolutely nobody noticed – but the couple of people who did, turned out to be perfectly well served by ADAL’s automatic use of cached refresh tokens.

Per the above, at this point we are reasonably confident that we can ship ADAL 3.x without leaking refresh tokens – and that’s good, because the moment of shipping is getting closer and closer (nope, I can’t share the exact date yet – sorry!).

That said, it is always possible that we missed some important scenario. That’s where YOU come into play. If you are using ADAL v2 and you are relying directly on refresh tokens bits anywhere in your code, please get in touch with us – we would like to understand whether this means we need to bring refresh tokens back after all, and if there is a way of achieving the functionality we need using ADAL cache… we would love the opportunity to show you how.

Thanks in advance for all your feedback, and happy coding!