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:

Get the library

You can get Microsoft Identity Web from NuGet, .NET Core project templates, and GitHub.

NuGet

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:

Project templates

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:

Diagram of the available dot net CLI project templates for Microsoft Identity Web
* MultiOrg is not supported with webapi2, but can be enabled in appsettings.json by setting tenant to common or organizations
** --calls-graph is not supported for Azure AD B2C

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

GitHub

Microsoft Identity Web is an open-source project hosted on GitHub: AzureAD/microsoft-identity-web

The repository wiki contains additional documentation, and if you need help or discover a bug, you can file an issue.

Features

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
  • Work or school accounts
  • Social identities (with Azure AD B2C)
  • Work or school accounts
  • Personal Microsoft accounts
  • Social identities (with Azure AD B2C)
  • Protect web APIs
  • Work or school accounts
  • Social identities (with Azure AD B2C)
  • Work or school accounts
  • Personal Microsoft accounts
  • Social identities (with Azure AD B2C)
  • 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
    WWW-Authenticate header generation in web APIs No Yes

    Next steps

    To see Microsoft Identity Web in action, try our Blazor Server tutorial:

    Tutorial: Create a Blazor Server app that uses the Microsoft identity platform for authentication

    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: