Hi everyone! We're excited to announce that…

Microsoft.Identity.Web is now generally available!

The Why

Building ASP.NET Core web apps or web APIs using the Microsoft identity platform used to require a lot of effort and domain and technical knowledge. Moreover, if developers wanted to call a downstream web API, this became extremely hard and frustrating. Although the Microsoft identity platform provides the basic building blocks to build ASP.NET Core web apps or web APIs with Identity.Model (middleware to validate tokens) and MSAL.NET (to acquire tokens), the task of doing so is challenging and difficult for our customers. In the past, customers often tried to glue together ASP.NET Core, middleware, and MSAL.NET and often got it wrong, resulting in a poor customer experience, lack of app/API reliability, and security vulnerabilities.

Today, when you use the ASP.NET Core 3.1 templates or the “File > New project” experience in Visual Studio, you create web apps or web APIs that target the Azure AD v1.0 endpoint. These apps are not secured by default: there is no support for issuer validation in multi-tenant apps, no validation of scope/roles in web APIs, and you have to write your own logic to use client certificates or decrypt certificates. Also, the developer experience is different between Azure AD and Azure AD B2C, and using external identities was incompatible with other identity providers.

Microsoft.Identity.Web brings a renewed, simplified, end-to-end experience for developers to build secured-by-default web apps or web APIs, possibly calling Microsoft Graph or other web APIs.

The What

Microsoft.Identity.Web provides an API with a pay as you go learning curve, making simple things simple and more complex scenarios possible, while enabling you to create web apps that sign-in users and create protected web APIs. Developers can incrementally add calls to Microsoft Graph or other web APIs. Microsoft.Identity.Web also provides project templates for web APIs and web apps, including MVC, Razor, and Blazor.

The NuGet packages

Microsoft.Identity.Web is released on NuGet.org as a set of NuGet packages:

• Microsoft.Identity.Web which is the main API.
• Microsoft.Identity.Web.UI brings the button to sign in and sign out users and handle some B2C experiences. It includes the challenge mechanism that enables the library to automatically handle incremental consent and conditional access. The UI is customizable.
• Microsoft.Identity.Web.MicrosoftGraph exposes the Microsoft Graph SDK for .NET, GraphServiceClient, so that it’s used in your controllers.
• Microsoft.Identity.Web.MicrosoftGraphBeta exposes the Microsoft Graph SDK beta for .NET (corresponding to the Microsoft Graph Beta endpoint).

Getting Started

Quickstarts, tutorials, and samples

Several quickstarts, tutorials, and samples now use Microsoft.Identity.Web:

• Quickstarts for ASP.NET Core web apps and web APIs. A bit more work is required to add the web API quickstart to the portal.
• Web apps, web APIs, daemon app calling a web API incremental tutorials, and a Blazor Server tutorial
• JavaScript samples calling a web API: Angular SPA, React SPA OBO, Angular SPA with roles and groups, Angular SPA multi-tenant API.

The scenario articles on docs.microsoft.com were also updated, and more is coming as we migrate the wiki to docs.microsoft.com.

ASP.NET 5.0

If you’ve installed the ASP.NET Core 5.0 SDK preview and create a Web App or Web API project, then by default you’ll be using Microsoft.Identity.Web and the new project templates. .NET 5.0 will GA in November.

ASP.NET core 3.1 templates

If you still use .NET Core 3.1, you can get the same project templates from NuGet. See https://aka.ms/ms-id-web/webapp-project-templates and https://aka.ms/ms-id-web/webapi-project-templates for details. The picture below shows the .NET CLI commands to use depending on your scenario:

The public API

If you're not creating your project with the project templates, for instance if you want to add authentication with Microsoft to an existing ASP.NET Core web app or API, you can do so in 3 steps:

Case of an Azure AD app

1. Update a configuration file to match the app registration according to your scenario.

   

2. Update the Startup.cs file to configure services appropriate for your scenario.

   

3. Update your controllers or Razor pages to validate scopes (in web APIs), or use Microsoft Graph or the downstream API helper to call a downstream API. The example below shows the code used to call Microsoft Graph.

   

   This one shows the code used to call a downstream API which is not Microsoft Graph

Case of an Azure AD B2C app

1. Update a configuration file to match the app registration according to your scenario.

   

2. Update the Startup.cs file to configure services appropriate for your scenario. This is the same as for Azure AD, except that B2C web API cannot call downstream APIs (OBO is not supported in B2C), and B2C apps don't call Microsoft Graph also the section name is typically named "AzureADB2C" instead of "AzureAD".

   

3. Update your controllers or Razor pages to validate scopes (in web APIs), or use the downstream API helper to call a downstream API.

   

See also the Official blog post announcing Microsoft.Identity.Web GA