Microsoft.Identity.Web is now generally available!

Office Add-ins team

We’re excited to announce that Microsoft.Identity.Web is now generally available. 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 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. Although the Microsoft identity platform provides the basic building blocks to build ASP.NET Core web apps or web APIs with Identity.Model (middleware) and MSAL.NET (to acquire tokens), the task of doing so is challenging. 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.

your ASP.NET Core web app or web API requires gluing together ASP.NET Core authentication middleware, MSAL.NET (if you call APIs), Identity model (to validate the tokens), and all that sits on top of .NET Core. Microsoft.Identity.Web is this glue

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.

 

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:

  • Identity.Web which is the main API.
  • 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.
  • Identity.Web.MicrosoftGraph exposes the Microsoft Graph SDK for .NET, GraphServiceClient, so that it’s used in your controllers.
  • Identity.Web.MicrosoftGraphBeta exposes the Microsoft Graph SDK beta for .NET (corresponding to the Microsoft Graph Beta endpoint).

Microsoft.Identity.Web project templates bring many features on top of what ASP.NET Core 3.1 was supporting

Getting Started

 Quickstarts, tutorials, and samples

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

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 in 5.0

If you’ve installed the ASP.NET Core 5 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:

This image presents the templates brought by Microsoft Identity Web depending on your scenario, what command to use, for which sign-in audience, and optionally when you want to call a web API (including Microsoft Graph)

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:

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

Details of the appsettings.json for a web app and a web API
Details of the appsettings.json for a web app and a web API

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

Code to add to your Startup.cs file for a web app and web API, depending on your scenario
Code to add to your Startup.cs file for a web app and web API, depending on 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.

Code to add to your Controller or Razor page file for a web app and web API, depending on your scenario
Code to add to your Controller or Razor page file for a web app and web API, depending on your scenario

– Please reach out to the Microsoft.Identity.Web repository, with any feedback or questions.

Feedback usabilla icon