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.

You can get Microsoft.Identity.Web from NuGet or by using a Visual Studio project template to create a new app project.

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

Install from 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:

• 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.

Install by using a Visual Studio project template

Several project templates that use Microsoft Identity Web are included in .NET SDK versions 5.0 and above. The project templates aren't included in the ASP.NET Core 3.1 SDK, but you can install them separately.

.NET 5.0+ - Project templates included

The Microsoft Identity Web project templates are included in .NET SDK versions 5.0 and above.

This example .NET CLI command creates a Blazor Server project that includes Microsoft Identity Web.

dotnet new blazorserver --auth SingleOrg --calls-graph --client-id "00000000-0000-0000-0000-000000000000" --tenant-id "11111111-1111-1111-1111-111111111111" --output my-blazor-app

Don't append a 2 to the application type argument (blazorserver in the example) if you're using the templates included in .NET SDK 5.0+. Include the 2 suffix only if you're on ASP.NET Core 3.1 and you installed the templates separately as described in the next section.

ASP.NET Core 3.1 - Install the project templates

If you're using ASP.NET Core 3.1, install the project templates from NuGet.

dotnet new --install Microsoft.Identity.Web.ProjectTemplates

For ASP.NET Core 3.1 only, append a 2 to the application type argument when you create a new project:

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

The following diagram shows several of the available app type templates and their arguments. Append a 2 to the app type argument (blazorserver2 in the example) only if you're using the ASP.NET Core 3.1 SDK and you installed the templates by using dotnet new --install.

^* 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

Features of the project templates

Microsoft Identity Web includes several features not available in the default ASP.NET Core 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:

• Using certificates with Microsoft.Identity.Web (GitHub)
• Incremental consent and conditional access (GitHub)