Home

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

• Getting Started
  • Getting started with MSAL.NET
  • Details on the ways to acquire tokens
  • Advanced topics
  • Testimonials
• Roadmap
• Samples
• FAQ

Conceptual documentation

Getting started with MSAL.NET

1. What are the authentication scenarios, why use MSAL.NET? for which application architectures?, and which platforms / target OS?
2. Prerequisite: you need to Register your app with Azure Active Directory
3. Type of Client Applications: public client applications and confidential client applications
4. Acquiring Tokens to access a protected API

Details on the ways to acquire tokens

Acquiring tokens from cache in any app

• AcquireTokenSilentAsync enables you to get a previously cached token

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

• Acquiring a token interactively enables the application to acquire a token after authenticating the user through an interactive sign-in. There are specificities, though depending on the platforms (Xamarin Android, Xamarin iOS, or UWP)
• Acquiring a token silently, on a Windows domain or AAD joined machine with Integrated Windows Authentication, or by using Username/passwords (not recommended)
• Acquiring a token on a text only device, by directing the user to sign-in on another device, by leveraging the Device Code Flow

Acquiring tokens in Web Apps / Web APIs / daemon apps (confidential client applications)

• Acquiring a token for the app (without a user) with client credential flows
• Acquiring a token on behalf of a user in services to services calls
• Acquiring a token for the signed-in user by authorization code in Web Apps

Advanced topics

• Handling Exceptions in MSAL in MSAL.Net
  • Retry-After
• How to customize the Token cache serialization
• How to enable diagnostics and Logging in MSAL.NET apps
• Differences between ADAL.NET and MSAL.NET apps, and how to migrate and ADAL.NET app to MSAL.NET

Testimonials

We've seen a lot of successful ADAL to MSAL migrations from a wide variety of partner teams. We provide migration documentation, and will assist with the migration as much as possible, if needed. Here are some testimonials from our happy partner teams!

“The Azure Portal had a mighty task of migrating from ADAL to MSAL with the constraint of maintaining the current Auth architecture. The MSAL team followed a very systematic migration process. They understood the Azure Portal's auth architecture, recommended solutions that fit in the current architecture. Following those guidelines, the Portal team was able to build a successful prototype, both teams did a final design review and eventually the changes were formalized for production. All questions, issues and blockers that came along the way were dealt with in a timely manner and with great patience and communication. Eventually the Azure Portal was able to successfully migrate from ADAL to MSAL without causing any outages in production.” -Akshay, Azure Portal Team

“Our success rate went up about 8% overall but the biggest gain was for Android with over 10% gain thanks to the added support for broker scenarios.” – Benoit, Azure Mobile App

"Converting Visual Studio from ADAL to MSAL has allowed us to better support Conditional access and Multi-factor authentication. Converting Visual Studio from ADAL to MSAL was made possible through the great support of the MSAL team. MSAL provides us a path forward for accessing new AAD features which benefit our customers." - Chris, Visual Studio

Roadmap

Date	Release	Blog post	Main features
(Not Started)	MSAL Future		Optional Claims, Note: Managed identity support is now available in Azure Identity in preview, this means all Azure SDK's will have this support built in)
(Next/In progress)	See milestones
Releases	All releases
Mar 15, 2023	4.51.0	MSAL 4.51.0	Simplified managed identity API, added ability to remove long-running OBO tokens and bug fixes, WAM bug fixes.
Feb 10, 2023	4.50.0	MSAL 4.50.0	Managed identity support for Azure Cloud Shell; bug fixes related to WAM preview, JSON serialization on .NET 7, Username/Password flow.
Dec 19, 2022	4.49.1	MSAL 4.49.1	Managed identity support for Azure Arc
Dec 16, 2022	4.49.0	MSAL 4.49.0	Added managed identity support, ability to disable instance discovery, new APIs to work with WWW-Authenticate and Authentication-Info headers, ability to acquire Work and School accounts in new WAM broker preview, performance improvements.
Nov 2, 2022	4.48.0	MSAL 4.48.0	Added .NET 6 targets; removed .NET 6 and Xamarin.Mac targets; GA'ed public client PoP API; bug fixes.
Oct 3, 2022	4.47.2	MSAL 4.47.2	Hide legacy API's that are available only to internal Microsoft only (1P) applications; Soft deprecate WithAuthority API on AcquireTokenXXX methods. Instead use WithTenantId or WithTenantIdFromAuthority, or WithB2CAuthority for B2C authorities; Logging error codes to MSAL Telemetry; Improve extensibility APIs to support new POP; bug fixes.
Sep 17, 2022	4.47.1	MSAL 4.47.1	Fixes an internal (Microsoft 1P only) NuGet feed issue.
Sep 16, 2022	4.47.0	MSAL 4.47.0	Support for .NET MAUI is now generally available for iOS, Windows and Android targets; MSAL logging feature is now generally available; Added IsProofOfPosessionSupportedByClient to determine if the current broker supports PoP; ability to turn off the default retry-once policy on 5xx errors; new public builder API accepting instances of ITelemetryClient; bug fixes.
Aug 29th, 2022	4.46.2	MSAL 4.46.2	Changed to an improved implementation of HTTP client factory on .NET Framework to improve resiliency; Logging additional exceptions to telemetry; bug fixes.
Aug 17th, 2022	4.46.1	MSAL 4.46.1	Added Explicit .net 461 support to new WAM Preview broker; Added MSALRuntime TelemetryData to verbose logging when a broker exception is thrown; Minor clarifications in caching logs.
Aug 4th, 2022	4.46.0	MSAL 4.46.0	AcquireTokenByUsernamePassword with PoP support in WAM broker preview; deprecated SecureString; exposed Identity Logger in caching code.
July 8th, 2022	4.46.0-preview	MSAL 4.46.0-preview	Support for .NET 6 iOS and Android targets.
Jun 23rd, 2022	4.45.0	MSAL 4.45.0	Upgrade to .NET Standard 2.0; improved logger API. Please note the changes developers need to make to their apps.
May 20th, 2022	4.44.0	MSAL 4.40.0	Public Preview of Proof of Possession tokens for public client desktop Windows apps, based on new integration with Windows Broker.
May 2nd, 2022	4.43.2	MSAL 4.43.2	Fix for Service Principals using refresh tokens in long-running OBO.
April 18th, 2022	4.43.1	MSAL 4.43.1	Embedded WebView SSO bug fix for desktop apps.
April 5th, 2022	4.43.0	MSAL 4.43.0	MAM support in Android; WAM bug fixes; system browser support in WSL2; UWP app packaging bug fix.
March 15th, 2022	4.42.1	MSAL 4.42.1	WAM bug fix related to /organizations authority. Fix for packaging UWP apps.
March 1st, 2022	4.42.0	MSAL 4.42.0	Multi-cloud support in interactive flow; MAM support in iOS; expose region used in AuthenticationResult; bug fixes.
February 7th, 2022	4.41.0	MSAL 4.41.0	WAM bug fixes and support improvements; support for Microsoft Edge as broker in Linux.
January 7th, 2022	4.40.0	MSAL 4.40.0	Hybrid SPA is generally available. Allow POP token to be created externally. Improved performance, logging.
November 29th, 2021	4.39.0	MSAL 4.39.0	Additional health metrics logging, multi-threading bug fix.
November 19th, 2021	4.38.0	MSAL 4.38.0	Added Hybrid SPA support. Added new specific API for long running web APIs, in addition to AcquireTokenOnBehalfOf**, which no longer requests refresh tokens. Added the correlation ID used in calls to Azure AD as part of cache callback (TokenCacheNotificationArgs).
October 22nd, 2021	4.37.0	MSAL 4.37.0	Improved user token cache performance, improved token refresh performance, added ability to enable shared internal cache, improved support for regional endpoints, ability to specify tenant ID at the request level, added cache refresh and token endpoint to AuthenticationResultMetadata.
October 6th, 2021	4.37.0-preview	MSAL 4.37.0-preview	Improved user token cache performance, improved token refresh performance, added ability to enable shared internal cache, improved support for regional endpoints.
September 29th, 2021	4.36.2	MSAL 4.36.2	Fixed a regression in authentication with the iOS broker.
September 8th, 2021	4.36.1	MSAL 4.36.1	Support for Application ID URIs to be used in confidential client applications.
August 31st, 2021	4.36.0	MSAL 4.36.0	Improved app token cache performance, improved token refresh timing, MSA-Passthrough with WAM, more actionable error messaging.
July 30th, 2021	4.35.1	MSAL 4.35.1	Performance fixes
July 23rd, 2021	4.35.0	MSAL 4.35.0	IAccount now provides TenantProfiles
July 8th, 2021	4.34.0	MSAL 4.34.0	WAM is now generally available. WWW-Authenticate support
June 15th, 2021	4.32.1		Improved logging for cache performance and bug fixes
June 3rd, 2021	4.32.0	MSAL 4.32.0	Kerberos support. Allow developers to inject XML federation metadata for IWA, bug fixes for IWA, fix UWP cache for multi-threaded operations, WAM fixes.
May 11th, 2021	4.31.0	MSAL 4.31.0	Additional metrics in AuthenticationResultMetadata, option to hide iOS security prompt for system browser, WAM related fixes.
April 27th, 2021	4.30.1	MSAL 4.30.1	MSAL.NET encodes data correctly when communicating with Android broker.
April 22nd, 2021	4.30.0	MSAL 4.30.0	PKCE support during confidential client auth code flow and bug fixes. Partitioned token serialization cache for client credential flow
March 23rd, 2021	4.28.1	MSAL 4.28.1	MSAL.NET now honors the shouldClearExistingCache when deserializing a null or empty blob.
February 19th, 2021	4.28.0	MSAL 4.28.0	A modern embedded browser on all platforms, helpers methods for public client apps.
February 19th, 2021	4.27.0	MSAL 4.27.0	Updated communication mechanism used in brokered authentication on Android to improve reliability and avoid power optimization issues
February 10th, 2021	4.26.0	MSAL 4.26.0	Added support for MSA-passthrough with WAM. Bug fixes.
January 20th, 2021	4.25.0	MSAL 4.25.0	Improvements to WAM and regional auth. WAM support moved to Microsoft.Identity.Client.Desktop package. Bug fixes.
History			Memory lane

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

Samples

At the bottom of each article for a given flow, you will find a table of samples relevant for this flow.

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

FAQ

• How MSAL.NET uses Web browsers for interactive authentication
• if you have issues with Xamarin.Forms applications leveraging MSAL.NET please read Troubleshooting-Xamarin.Android-issues-with-MSAL