Edit

Microsoft Authentication Library for .NET

  • Article

MSAL.NET (Microsoft.Identity.Client) is an authentication library that enables you to acquire tokens from Microsoft Entra ID, to access protected web APIs (Microsoft APIs or applications registered with Microsoft Entra ID). MSAL.NET is available on several .NET platforms (Desktop, Universal Windows Platform, MAUI, Xamarin Android, Xamarin iOS, Windows 8.1, and .NET Core).

Get MSAL.NET >

Supported platforms and application architectures

MSAL.NET supports different application topologies, including:

  • Native clients (mobile or desktop applications) calling the Microsoft Graph API on behalf of a user,
  • Daemons, services, or web clients (web apps or web APIs) calling the Microsoft Graph API on behalf of a user, or without a user.

With the exception of User-agent based client which is only supported in JavaScript.

For more details about the supported scenarios, see Scenarios.

MSAL.NET supports multiple platforms, including .NET Framework, .NET Core(including .NET 6), MAUI, Xamarin Android, Xamarin iOS, and UWP.

Note

Not all the authentication features are available in all platforms, mostly because:

  • Mobile platforms (Xamarin, MAUI and UWP) do not allow confidential client flows, because they are not meant to function as a backend and cannot store secrets securely.
  • On public clients (mobile and desktop), the default browser and redirect URIs are different from platform to platform and broker availability varies (details in browser usage documentation).

Most of the articles in this MSAL.NET reference content describe the most complete platform (.NET Framework), but, topic by topic, it occasionally calls out differences between platforms.

Why use MSAL.NET ?

MSAL.NET (Microsoft Authentication Library for .NET) enables developers of .NET applications to acquire tokens in order to call secured web APIs. These web APIs can be the Microsoft Graph API, other Microsoft APIS, 3rd party Web APIs, or your own Web API.

As a token acquisition library, MSAL.NET provides several ways of getting a token, with a consistent API for a number of platforms. Using MSAL.NET adds value over using OAuth libraries and coding against the protocol by:

  • Maintains a token cache and refreshes tokens for you when they are close to expire.
  • Eliminates the need for you to handle token expiration by yourself.
  • Helps you specify which audience you want your application to sign-in (your organization, several organizations, work and school and Microsoft personal accounts, social identities with Azure AD B2C, users in sovereign and national clouds).
  • Helps you set-up the application through configuration files.
  • Helps you troubleshoot the app by exposing actionable exceptions, logging, and telemetry.

MSAL.NET is about acquiring tokens, not protecting an API

MSAL.NET is used to acquire tokens. It's not used to protect a Web API. If you are interested in protecting a Web API with Microsoft Entra ID, you might want to check out:

Conceptual documentation

Getting started with MSAL.NET

  1. Learn about MSAL.NET usage scenarios.
  2. You will need to register your app with Microsoft Entra ID.
  3. Learn about the types of client applications: public client and confidential client.
  4. Learn about acquiring tokens to access a protected API.

Acquiring tokens

Acquiring tokens from cache in any app

Acquiring tokens in desktop and 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 implementation-specific details depending on the target platforms, such as Xamarin Android or UWP.
  • Acquiring a token silently on a Windows domain or Microsoft Entra 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 with the Device Code Flow.
  • Acquiring a token using the Web Account Manager (WAM), a Windows OS component that acts a broker allowing the users of your app benefit from integration with accounts known to Windows.

Acquiring tokens in web apps, web APIs, and daemon apps (confidential client applications)

Confidential client availability

MSAL.NET is a multi-framework library. All confidential client flows are available on:

  • .NET Core
  • .NET Desktop
  • .NET Standard

They are not available on the mobile platforms, because the OAuth2 spec states that there should be a secure, dedicated connection between the application and the identity provider. This secure connection can be achieved on web servers and web API back-ends by deploying a certificate (or a secret string, but this is not recommended for production). It cannot be achieved on mobile apps and other client applications that are distributed to users. As such, these confidential flows are not available on:

  • Xamarin.Android / MAUI Android
  • Xamarin.iOS / MAUI iOS
  • UWP and WinUI

Migration from Azure Active Directory Authentication Library (ADAL)

Microsoft Authentication Library (MSAL) for .NET is the supported library that can be used for authentication token acquisition. If you or your organization are using the Azure Active Directory Authentication Library (ADAL), you should migrate to MSAL. ADAL will reach end-of-life by June 30, 2023.

Note

While ADAL will be deprecated on June 30, 2023, applications depending on ADAL should not break as the underlying endpoint will remain active. However, no new features or support will be offered for ADAL.

Releases

For previous releases, see the Releases page on GitHub. Minor (feature) releases are published every month. A feature could be included in a release or not depending on its complexity. Smaller patch or urgent fixes can be releases more frequently. Some of the security issues are back ported to the last major/minor release.

For work-in-progress and future releases, see Milestones.

For additional information on versioning, see Semantic versioning - API change management to understand changes in MSAL.NET public API.

Samples

See our comprehensive sample list.

FAQ