Home

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).

• Roadmap
• Conceptual Documentation
• FAQ

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
June 13th 2019	ADAL 5.1.0	See 5.0.1 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

Introduction

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 interactively in public client applications

  • Controlling the interactivity with the user: PlatformParameters
    • Properties common to all platforms
    • Property specific to mobile platforms relative to the brokers
    • Properties specific to iOS to fine grain control the UX
    • Properties specific to WinRT and UWP to use Corporate networks

• Acquiring token without user interaction

  • AcquireTokenSilentAsync using the token cache (and refreshing silently)
  • AcquireTokenSilentAsync using Windows Integrated Authentication on Windows (Kerberos)
  • Acquiring a token with username and password (only for .NET Framework, and not recommended)

• Leverage Device Code Flow to acquire tokens on devices without a Web browser

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

• Acquiring a token without a user (in the name of the application) with Client credentials
  • with application secret
  • with certificate
  • Acquiring a token with a Client assertion
• Acquiring tokens on behalf of a user (Service to service calls)
• Acquiring a token for the signed-in user by authorization code (in Web Apps)

Handling exceptions and errors in ADAL.NET

• Exception types
• Best practices on handling ADAL.NET exceptions

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

Samples

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

FAQ

• How ADAL.NET uses a browser for interactive authentication
• Q&A
• About non_https_redirect_failed Exceptions
• Which version of ADAL work with Azure Active Directory Seamless Single Sign-On