Choosing a version of MSAL.NET

Depending on the type of application you're building, and its underlying platform, you can choose to use MSAL.NET, Microsoft Identity Web, or both.

Microsoft Identity Web is a set of ASP.NET Core libraries that simplifies adding authentication and authorization support to web apps and web APIs integrating with the Microsoft identity platform. It provides a single-surface API convenience layer that ties together ASP.NET Core, its authentication middleware, and the Microsoft Authentication Library (MSAL) for .NET.

Follow the decision tree below to determine whether your scenario requires MSAL.NET, Microsoft Identity Web, or both.

When do I use MSAL.NET

You're building a desktop or mobile app. Use MSAL.NET directly and start acquiring tokens for your public client application. For details see:

• Acquiring token in a desktop app, and using WAM
• Acquiring token in a mobile application

Use Microsoft Identity Web

You're building a confidential client application (Web app, web API, daemon/service app) running on ASP.NET Core, ASP.NET OWIN, or .NET framework/.NET Core. See what Microsoft Identity Web has to offer:

• Sign users in via web apps in Microsoft Entra ID, Azure AD B2C, and Microsoft Entra External ID applications
  • Support Microsoft personal accounts
  • Support guest users
  • Incremental consent and conditional access in web apps
  • Handle SameSite
  • Integrates with "App services authentication"
  • Supports PKCE for confidential client applications
  • Brings performant token cache serializers, including distributed
• Protect web API (with Microsoft Entra ID, Azure AD B2C, or Microsoft Entra External ID)
  • Validates the issuer (including in-multi-tenant apps, any cloud)
  • supports token decrypt certificates in Web APIs
  • Validates Scope and app role in Web APIs
  • Generates WWW-authenticate headers in APIs (CA, CAE)
  • Protect gRPC services and Azure functions
• Web app/API calling downstream APIs (including graph except for B2C)
  • Call downstream APIs without having to manage authentication and tokens yourself.
  • Integrates with the graph SDK, and the Azure SDKs
  • Describe the client credentials, and Microsoft.Identity.Web fetches them for you (for instance certificates from Key Vault, or workload identity federation with Azure Kubernetes Service (AKS) and Managed Identities)
• Supports multiple Authentication schemes in ASP.NET Core
• Supports Proof of Possession protocol
• Resilient (supports regional token acquisition and routing hint for the token backup system)

You're building a new application

Use the Project Templates and the msidentity-app-sync tool. We have web app templates for web MVC, Razor, Blazor server, Blazorwasm hosted and not hosted. All for Microsoft Entra ID or Azure AD B2C.

Web app project templates.

We have web API templates for gRPC and Azure Functions.

Web API project templates.

Here's information on how to run the msidentity-app-sync-tool which is a command line tool which creates Microsoft identity platform applications in a tenant (Microsoft Entra ID or Azure AD B2C) and updates the configuration code of your ASP.NET Core applications. The tool can also be used to update code from an existing Microsoft Entra application or Azure AD B2C application.

It's available on NuGet.

You're adding auth to an existing app or I'm migrating from ADAL

Just take the code you need from Microsoft Identity Web to update your app. Here's an example:

When do you use the hybrid model (MSAL.NET and Microsoft Identity Web)

You are building a SDK for confidential client applications and want to use MSAL.NET low level APIs. In MSAL.NET, an in-memory token cache is provided by default, however, in the case of web apps or web APIs, caching should be managed differently than for public client applications (desktop or mobile apps) as it requires to be partitioned correctly. It is highly recommended to leverage a token cache serializer, which can be a distributed cache, (e.g., Redis, Cosmos, or SQL Server, distributed in memory cache), or a correctly partitioned in memory cache.

By using token cache serializers you partition the token caches depending on the cache key that is used because the cache is swapped between the storage and MSAL's memory. This cache key is computed by MSAL.NET as a function of the flow you use

Why do you need Microsoft.Identity.Web.TokenCache?

Microsoft.Identity.Web.TokenCache provides token cache serialization for you. See Token cache serialization for details.

Examples of how to use token caches for web apps and web APIs are available in the ASP.NET Core web app tutorial in the phase 2-2 Token Cache. For implementations have a look at the TokenCacheProviders folder in the Microsoft.Identity.Web repository.

Microsoft Identity Web also helps with certificate loading.