Microsoft Identity Web authentication library
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.
Supported application scenarios
If you're building ASP.NET Core web apps or web APIs and want to use Azure Active Directory (Azure AD) or Azure AD B2C for identity and access management (IAM), we recommend using Microsoft Identity Web for all of these scenarios:
- Web app that signs in users
- Web app that signs in users and calls a web API on their behalf
- Protected web API that only authenticated users can access
- Protected web API that calls another (downstream) web API on behalf of the signed-in user
Get the library
Microsoft Identity Web is available on NuGet as a set of packages that provide modular functionality based on your app's needs. Use the .NET CLI's
dotnet add command or Visual Studio's NuGet Package Manager to install the packages appropriate for your project:
- Microsoft.Identity.Web - The main package. Required by all apps that use Microsoft Identity Web.
- Microsoft.Identity.Web.UI - Optional. Adds UI for user sign-in and sign-out and an associated controller for web apps.
- Microsoft.Identity.Web.MicrosoftGraph - Optional. Provides simplified interaction with the Microsoft Graph API.
- Microsoft.Identity.Web.MicrosoftGraphBeta - Optional. Provides simplified interaction with the Microsoft Graph API beta endpoint.
Microsoft Identity Web project templates are included in .NET 5.0 and are available for download for ASP.NET Core 3.1 projects.
If you're using ASP.NET Core 3.1, install the templates with the .NET CLI:
dotnet new --install Microsoft.Identity.Web.ProjectTemplates::1.0.0
The following diagram shows a high-level view of the supported app types and their relevant arguments:
This example .NET CLI command, taken from our Blazor Server tutorial, generates a new Blazor Server project that includes the right packages and starter code (placeholder values shown):
dotnet new blazorserver2 --auth SingleOrg --calls-graph --client-id "00000000-0000-0000-0000-000000000000" --tenant-id "11111111-1111-1111-1111-111111111111" --output my-blazor-app
Microsoft Identity Web is an open-source project hosted on GitHub: AzureAD/microsoft-identity-web
Microsoft Identity Web includes several features not provided if you use the default ASP.NET 3.1 project templates.
|Feature||ASP.NET Core 3.1||Microsoft Identity Web|
|Sign in users in web apps|
|Protect web APIs|
|Issuer validation in multi-tenant apps||No||Yes, for all clouds and Azure AD B2C|
|Web app/API calls Microsoft graph||No||Yes|
|Web app/API calls web API||No||Yes|
|Supports certificate credentials||No||Yes, including Azure Key Vault|
|Incremental consent and conditional access support in web apps||No||Yes, in MVC, Razor pages, and Blazor|
|Token encryption certificates in web APIs||No||Yes|
|Scopes/app role validation in web APIs||No||Yes|
To see Microsoft Identity Web in action, try our Blazor Server tutorial:
The Microsoft Identity Web wiki on GitHub contains extensive reference documentation for various aspects of the library. For example, certificate usage, incremental consent, and conditional access reference can be found here: