Skip to content
jennyf19 edited this page Feb 14, 2020 · 122 revisions
Clone this wiki locally

ADAL.NET (Microsoft.IdentityModel.Clients.ActiveDirectory) is an authentication library which enables you to acquire tokens from Azure AD and ADFS, to access protected Web APIs (Microsoft APIs or applications registered with Azure Active Directory). ADAL.NET is available on several .NET platforms (Desktop, Universal Windows Platform, Xamarin Android, Xamarin iOS, and .NET Core).


Innovation now happens in MSAL.NET. See also MSAL.NET roadmap

Date Release Blog post Main features
Future ADAL 5.x Act on community's, partners and customers feedback, Migration guide from ADAL to MSAL 3.x
** 5.x+ See release details here
February 14th 2020 ADAL 5.2.7 see 5.2.7 release Release notes for details
January 16th 2020 ADAL 5.2.6 see 5.2.6 release Release notes for details
December 12th 2019 ADAL 5.2.5 see 5.2.5 release Release notes for details
November 6th 2019 ADAL 5.2.4 See 5.2.4 release Improvements to iOS 13 with broker support)
October 14th 2019 ADAL 5.2.3 See 5.2.3 release Bug fixes for 1666
August 8th 2019 ADAL 5.1.1 See 5.1.1 release Bug fixes for 1627, 1622, and 1636
June 13th 2019 ADAL 5.1.0 See 5.1.0 release Bug fixes for 1606, 1604, 1610, and 1599.
May 3rd 2019 ADAL 5.0.5 See 5.0.5 release Bug fix for documentation - 1593
Apr 19th 2019 ADAL 5.03-preview See 5.0.3-preview release Bug fix 1580 - enabling sso in UWP and 1575 to propagate custom Httpclient exceptions.
Apr 4th 2019 ADAL 5.0.2-preview See 5.0.2-preview release Bug fix 1571 - deadlock with the cache in advanced desktop scenarios
Apr 1st 2019 ADAL 5.0.1-preview See 5.0.1-preview release Bug fixes, exception serialization, cancellation for Device Code Flow, Adding and HttpClientFactory parameter to the constructor, publication of symbols to the Microsoft symbol Server
Mar 7th 2019 ADAL 5.0.0-preview See 5.0.0-preview release Enhancements includes support for MSALv3 Cache (which is also or will soon be supported by other libraries such as Python and Java) as well as enabling users to bring their own browser as part of the Auth Code retrieval. The MSAL v3 notes talks in more details about these two additions.
Feb 8th 2019 ADAL 4.5.1 See 4.5.1 release and 4.5.0 release Bug fixes (Co-existence of ADAL 4 and MSAL 2.6, Xamarin Version update, Http timeout caused NullReferenceException, various updates for Broker scenarios, improved logging)
Nov 20th 2018 ADAL 4.4.1 See 4.4.0 release and 4.4.1 release Bug fixes (around the token cache in advanced scenarios, consistency between platforms, and stability in specific scenarios)
Oct 19th 2018 ADAL 4.3.0 See 4.3.0 release General availability of ADAL 4.x See Changes in ADAL.NET from 3.x to 4.x
Oct 17th 2018 ADAL 4.2.0-preview See 4.2.0-preview release Bug fixes on top of ADAL 4.0, improvement of error messages
Aug 28th, 2018 ADAL v4.0.0-preview Blog post about ADAL.NET 4.0.0-preview and MSAL.NET 2.0.0-preview Common cache format for ADAL.NET and MSAL.NET so that you can upgrade your applications to MSAL.NET and keep the SSO state. See Changes in ADAL.NET from 3.x to 4.x
Jun 16th, 2018 ADAL v3.19.8 See releases bug fixes, with UWP, .NET Core logs, iOS 11.3 resource leak, PKAuth update, keeping spaces in SAML tokens for better interop with federated IDPs
Jan 30th, 2018 ADAL v3.19.1 Blog post about ADAL.NET 3.19.4 and MSAL.1.1.2-preview Simplified Azure AD certificate Rollup, fixes SSO issues with brokers, compliance with GDPR
October 11th, 2017 ADAL v3.17.0 Adal.NET 3.17 released Support for conditional access, help customers not using the APIs that don't make sense depending on the platform. Support for PromptBehavior.SelectAccount and full support for certificates on .NET 4.7
July 11th, 2017 ADAL v3.14.1 Adal.NET 3.14.1 released Support of ClientAssertionCertificate in .NET Core platform

For previous, or intermediate releases, see releases. See also Semantic versioning - API change management to understand changes in ADAL.NET public API and ADAL release cadence to understand when ADAL.NET is released

Conceptual documentation


  1. Why use ADAL.NET ? for which application architectures? and which target OS?
  2. Pre-requisite: Register your application with Azure Active Directory
  3. Instantiate a AuthenticationContext: a connection to Azure AD
  4. Acquire a token for a user or the application itself. This returns an AuthenticationResult itself providing the UserInfo if the token is for a user.
  5. Use an access token to call a protected Web API
  6. Follow best practices for a robust enterprise ready application

Details on all the ways to acquire tokens

Acquiring tokens in Public client applications (Desktop/Mobile apps)

Acquiring tokens in Confidential client application flows (Web Apps, Web APIs, daemon apps)

Handling exceptions and errors in ADAL.NET

Advanced topics - Enterprise ready applications

  1. Special case of applications using Broker on iOS and Android (Xamarin iOS and Android)
  2. Implementing a custom Token Cache serialization (.NET Desktop | .NET Core)
  3. Troubleshooting an application using Logging
  4. Users and User management


Articles of a given topic in the conceptual documentation contains links (at the bottom of the page) to relevant samples for the topic

See also Azure AD V1.0 samples by scenario. All the .NET | ASP.NET | .NET Core | ASP.NET Core samples which acquire tokens leverage ADAL.NET